@api-client/core 0.5.24 → 0.5.27

package/src/events/transport/TransportEvents.ts

@@ -0,0 +1,116 @@
+import { IRequestAuthorization } from "../../models/RequestAuthorization.js";
+import { IHttpRequest } from "../../models/HttpRequest.js";
+import { IRequestBaseConfig } from "../../models/RequestConfig.js";
+import { IRequestLog } from '../../models/RequestLog.js';
+import { HttpProject } from "../../models/HttpProject.js";
+import { ContextEvent } from "../BaseEvents.js";
+import { TransportEventTypes } from "./TransportEventTypes.js";
+import { IProjectRunnerOptions } from "../../runtime/node/InteropInterfaces.js";
+import { IProjectExecutionLog } from "../../runtime/reporters/Reporter.js";
+
+export interface ICoreRequestDetail {
+  request: IHttpRequest; 
+  authorization?: IRequestAuthorization[]; 
+  config?: IRequestBaseConfig;
+}
+
+export interface IHttpRequestDetail {
+  request: IHttpRequest; 
+  init?: RequestInit;
+}
+
+export interface IProjectRequestDetail {
+  project: HttpProject | string; 
+  opts: IProjectRunnerOptions;
+}
+
+/* eslint-disable no-unused-vars */
+export const TransportEvent = Object.freeze({
+  /** 
+   * Transport via the CoreEngine.
+   */
+  Core: Object.freeze({
+    /**
+     * Sends a single request without a context of a project.
+     * 
+     * @param target The events target.
+     * @param request The request definition
+     * @param authorization When known, a list of authorization configuration to apply to the request.
+     * @param config Optional request configuration.
+     * @returns The execution log or `undefined` when the event was not handled.
+     */
+    send: async (target: EventTarget, request: IHttpRequest, authorization?: IRequestAuthorization[], config?: IRequestBaseConfig): Promise<IRequestLog | undefined> => {
+      const e = new ContextEvent<ICoreRequestDetail, IRequestLog>(TransportEventTypes.Core.send, {
+        request,
+        authorization,
+        config
+      });
+      target.dispatchEvent(e);
+      return e.detail.result;
+    },
+  }),
+  /** 
+   * Transport via the native platform's bindings.
+   */
+  Http: Object.freeze({
+    /**
+     * Sends the request outside the Core engine, most probably using Fetch API.
+     * Note, CORS may apply to the request.
+     * 
+     * @param target The events target
+     * @param request The base request definition.
+     * @param init Optional request init options compatible with the Fetch API.
+     * @returns Compatible with the Fetch API Response object or `undefined` when the event was not handled.
+     */
+    send: async (target: EventTarget, request: IHttpRequest, init?: RequestInit): Promise<Response | undefined> => {
+      const e = new ContextEvent<IHttpRequestDetail, Response>(TransportEventTypes.Http.send, {
+        request,
+        init,
+      });
+      target.dispatchEvent(e);
+      return e.detail.result;
+    },
+  }),
+
+  // project runner
+  Project: Object.freeze({
+    /**
+     * For both a request or a folder (since it's all single configuration.)
+     * 
+     * @param target The events target
+     * @param project The instance of a project or an id of the project to execute. The current user has to be already authenticated.
+     * @param opts The project execution options.
+     * @returns 
+     */
+    send: async (target: EventTarget, project: HttpProject | string, opts: IProjectRunnerOptions): Promise<IProjectExecutionLog | undefined> => {
+      const e = new ContextEvent<IProjectRequestDetail, IProjectExecutionLog>(TransportEventTypes.Project.send, {
+        project,
+        opts,
+      });
+      target.dispatchEvent(e);
+      return e.detail.result;
+    },
+  }),
+
+  // web sockets.
+  Ws: Object.freeze({
+    /** 
+     * Informs to make a connection. Used by web sockets.
+     */
+    connect: async (target: EventTarget): Promise<any> => {
+      throw new Error(`Not yet implemented`);
+    },
+    /** 
+     * Informs to close the current connection. Used by web sockets.
+     */
+    disconnect: async (target: EventTarget): Promise<any> => {
+      throw new Error(`Not yet implemented`);
+    },
+    /** 
+     * Informs to send a data on the current connection. Used by web sockets.
+     */
+    send: async (target: EventTarget): Promise<any> => {
+      throw new Error(`Not yet implemented`);
+    },
+  }),
+});

package/src/lib/transformers/PayloadSerializer.ts

@@ -2,6 +2,7 @@ import { blobToDataUrl } from './Utils.js';
 
 export type PayloadTypes = 'string' | 'file' | 'blob' | 'buffer' | 'arraybuffer' | 'formdata' | 'x-www-form-urlencoded';
 export type DeserializedPayload = string | Blob | File | FormData | Buffer | ArrayBuffer | undefined;
+export const SupportedPayloadTypes: PayloadTypes[] = ['string', 'file', 'blob', 'buffer', 'arraybuffer', 'formdata', 'x-www-form-urlencoded'];
 
 export interface IMultipartBody {
   /**
@@ -64,15 +65,41 @@ export const hasBuffer: boolean = typeof Buffer === 'function';
 
 export class PayloadSerializer {
   /**
-   * Transforms the payload into a data store safe object.
+   * Checked whether the passed payload can be safely stored in the data store.
+   * @param payload The value to test. 
    */
-  static async serialize(payload: DeserializedPayload): Promise<ISafePayload | string | undefined> {
-    if (typeof payload === 'undefined' || payload === null) {
-      return undefined;
+  static isSafePayload(payload: any): boolean {
+    if (payload === undefined || payload === null) {
+      // both values should be stored correctly
+      return true;
     }
     if (typeof payload === 'string') {
-      return payload;
+      return true;
+    }
+    // checks whether the payload is already serialized./
+    const typed = payload as ISafePayload;
+    if (typed.type && SupportedPayloadTypes.includes(typed.type)) {
+      return true
+    }
+    return false;
+  }
+
+  /**
+   * Transforms the payload into a data store safe object.
+   */
+  static async serialize(payload: DeserializedPayload): Promise<ISafePayload | string | undefined> {
+    if (PayloadSerializer.isSafePayload(payload)) {
+      if (payload === null) {
+        return undefined;
+      }
+      return (payload as unknown) as ISafePayload | string | undefined;
     }
+    // if (payload === undefined || payload === null) {
+    //   return undefined;
+    // }
+    // if (typeof payload === 'string') {
+    //   return payload;
+    // }
     if (hasBlob && payload instanceof Blob) {
       return PayloadSerializer.stringifyBlob(payload);
     }
@@ -129,8 +156,8 @@ export class PayloadSerializer {
   /**
    * When the passed argument is an ArrayBuffer it creates an object describing the object in a safe to store object.
    * 
-   * @param {any} payload 
-   * @returns {TransformedPayload|undefined} The buffer metadata or undefined if the passed argument is not an ArrayBuffer.
+   * @param payload 
+   * @returns The buffer metadata or undefined if the passed argument is not an ArrayBuffer.
    */
   static stringifyArrayBuffer(payload: ArrayBuffer): ISafePayload | undefined {
     if (payload.byteLength) {
@@ -164,9 +191,9 @@ export class PayloadSerializer {
   /**
    * Transforms a FormData entry into a safe-to-store text entry
    *
-   * @param {string} name The part name
-   * @param {string|File} file The part value
-   * @return {Promise<IMultipartBody>} Transformed FormData part to a datastore safe entry.
+   * @param name The part name
+   * @param file The part value
+   * @returns Transformed FormData part to a datastore safe entry.
    */
   static async serializeFormDataEntry(name: string, file: string | File): Promise<IMultipartBody> {
     if (typeof file === 'string') {
@@ -202,7 +229,7 @@ export class PayloadSerializer {
    * Restores the payload into its original format.
    */
   static async deserialize(payload: ISafePayload | string | undefined): Promise<DeserializedPayload> {
-    if (typeof payload === 'undefined' || payload === null) {
+    if (payload === undefined || payload === null) {
       return undefined;
     }
     if (typeof payload === 'string') {

package/src/mocking/ProjectMock.ts

@@ -3,6 +3,7 @@ import { Request } from './lib/Request.js';
 import { Response } from './lib/Response.js';
 import { User } from './lib/User.js';
 import { History } from './lib/History.js';
+import { Url } from './lib/Url.js';
 
 export { IRequestLogInit } from './lib/Request.js';
 export { IResponseInit } from './lib/Response.js';
@@ -14,6 +15,7 @@ export class ProjectMock extends DataMock {
   response: Response;
   user: User;
   history: History;
+  url: Url;
   
   /**
    * @param init The library init options.
@@ -24,5 +26,6 @@ export class ProjectMock extends DataMock {
     this.response = new Response(init);
     this.user = new User(init);
     this.history = new History(init);
+    this.url = new Url(init);
   }
 }

package/src/mocking/lib/Url.ts

@@ -0,0 +1,35 @@
+import { DataMockInit, Internet, Types } from "@pawel-up/data-mock";
+import { IUrl } from "../../models/Url.js";
+
+/**
+ * Mocks the URL data.
+ */
+export class Url {
+  types: Types;
+  internet: Internet;
+  
+  constructor(init: DataMockInit={}) {
+    this.types = new Types(init.seed);
+    this.internet = new Internet(init);
+  }
+
+  url(): IUrl {
+    const date = this.types.datetime();
+    const result: IUrl = {
+      url: this.internet.uri(),
+      cnt: this.types.number({ min: 0 }),
+      time: date.getTime(),
+    };
+    date.setHours(0, 0, 0, 0);
+    result.midnight = date.getTime();
+    return result;
+  }
+
+  urls(size=25): IUrl[] {
+    const result: IUrl[] = [];
+    for (let i = 0; i < size; i++) {
+      result.push(this.url());
+    }
+    return result;
+  }
+}

package/src/models/RequestConfig.ts

@@ -59,6 +59,12 @@ export interface IRequestBaseConfig {
    * Whether the processor should validate certificates.
    */
   validateCertificates?: boolean;
+
+  /**
+   * Optional signal from an `AbortController`.
+   * This is populated only when executing a request. This value is opaque for the data store.
+   */
+  signal?: AbortSignal;
 }
 
 /**
@@ -150,6 +156,12 @@ export class RequestConfig {
    */
   sentMessageLimit?: number;
 
+  /**
+   * Optional signal from an `AbortController`.
+   * This is populated only when executing a request. This value is opaque for the data store.
+   */
+  signal?: AbortSignal;
+
   static withDefaults(): RequestConfig {
     return new RequestConfig({
       kind: Kind,
@@ -209,7 +221,7 @@ export class RequestConfig {
   new(init: IRequestConfig): void {
     const { 
       enabled, followRedirects, ignoreSessionCookies, validateCertificates, defaultHeaders, timeout, hosts, variables,
-      defaultAccept, defaultUserAgent, proxy, proxyPassword, proxyUsername, sentMessageLimit,
+      defaultAccept, defaultUserAgent, proxy, proxyPassword, proxyUsername, sentMessageLimit, signal,
     } = init;
     this.kind = Kind;
     if (typeof enabled === 'boolean') {
@@ -282,6 +294,11 @@ export class RequestConfig {
     } else {
       this.sentMessageLimit = undefined;
     }
+    if (signal) {
+      this.signal = signal;
+    } else {
+      this.signal = undefined;
+    }
   }
 
   toJSON(): IRequestConfig {
@@ -310,6 +327,7 @@ export class RequestConfig {
     if (Array.isArray(this.variables)) {
       result.variables = this.variables.map(i => i.toJSON());
     }
+    // DO NOT put the `signal` here.
     return result;
   }
 }

package/src/models/SerializablePayload.ts

@@ -17,11 +17,7 @@ export class SerializablePayload {
    */
   async writePayload(message: unknown): Promise<void> {
     this._sourcePayload = message;
-    if (typeof message === 'string') {
-      this.payload = message;
-    } else {
-      this.payload = await PayloadSerializer.serialize(message as DeserializedPayload);
-    }
+    this.payload = await PayloadSerializer.serialize(message as DeserializedPayload);
   }
 
   /**

package/src/runtime/http-engine/CoreEngine.ts

@@ -74,7 +74,7 @@ export class CoreEngine extends HttpEngine {
       } else {
         await this.connect();
       }
-      if (!this.socket) {
+      if (!this.socket || this.aborted) {
         return;
       }
       const message = await this.prepareMessage();

package/src/runtime/http-engine/HttpEngine.ts

@@ -191,6 +191,31 @@ export abstract class HttpEngine extends EventEmitter {
   protected mainRejecter?: (err: SerializableError) => void;
   [mainPromiseSymbol]?: Promise<IRequestLog>;
 
+  protected _signal?: AbortSignal;
+
+  /**
+   * The abort signal to set on this request.
+   * Aborts the request when the signal fires.
+   * @type {(AbortSignal | undefined)}
+   */
+  get signal(): AbortSignal | undefined {
+    return this._signal;
+  }
+
+  set signal(value: AbortSignal | undefined) {
+    const old = this._signal;
+    if (old === value) {
+      return;
+    }
+    this._signal = value;
+    if (old) {
+      old.removeEventListener('abort', this._abortHandler);
+    }
+    if (value) {
+      value.addEventListener('abort', this._abortHandler);
+    }
+  }
+
   constructor(request: IHttpRequest, opts: HttpEngineOptions = {}) {
     super();
     this.request = new HttpRequest({ ...request });
@@ -199,6 +224,11 @@ export abstract class HttpEngine extends EventEmitter {
     this.sentRequest = new SentRequest({ ...request, startTime: Date.now() });
     this.uri = this.readUrl(request.url);
     this.hostHeader = RequestUtils.getHostHeader(request.url);
+
+    this._abortHandler = this._abortHandler.bind(this);
+    if (opts.signal) {
+      this.signal = opts.signal;
+    }
   }
 
   /**
@@ -245,6 +275,15 @@ export abstract class HttpEngine extends EventEmitter {
     this.socket = undefined;
   }
 
+  /**
+   * Handler for the `abort` event on the `AbortSignal`.
+   */
+  protected _abortHandler(): void {
+    const e = new SerializableError('Request aborted', 3);
+    this._errorRequest(e);
+    this.abort();
+  }
+
   /**
    * Sends the request.
    */

package/src/runtime/node/InteropInterfaces.ts

@@ -118,4 +118,10 @@ export interface IProjectRunnerOptions {
    * When not set it does not read system variables.
    */
   variables?: boolean | string[] | Record<string, string>;
+
+  /**
+   * Optional signal from an `AbortController`.
+   * It aborts the execution when the ``abort` event is dispatched.
+   */
+  signal?: AbortSignal;
 }

package/src/runtime/node/ProjectParallelRunner.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'url';
 import { HttpProject } from '../../models/HttpProject.js';
 import { IProjectExecutionLog, IProjectExecutionIteration } from '../reporters/Reporter.js';
 import { BaseRunner } from './BaseRunner.js';
+import { State } from './enums.js';
 import { IProjectParallelRunnerOptions, IProjectParallelWorkerOptions } from './InteropInterfaces.js'
 
 const numCPUs = cpus().length;
@@ -74,9 +75,13 @@ export class ProjectParallelRunner extends BaseRunner {
   constructor(project: HttpProject, opts: IProjectParallelRunnerOptions = {}) {
     super();
     this.project = project;
-    this.options = opts || {};
+    this.options = opts;
 
     this._exitHandler = this._exitHandler.bind(this);
+    this._abortHandler = this._abortHandler.bind(this);
+    if (opts.signal) {
+      this.signal = opts.signal;
+    }
   }
 
   execute(): Promise<IProjectExecutionLog> {
@@ -87,7 +92,70 @@ export class ProjectParallelRunner extends BaseRunner {
     });
   }
 
+  protected _state: State = State.Idle;
+
+  get state(): State {
+    return this._state;
+  }
+
+  protected _signal?: AbortSignal;
+
+  /**
+   * The abort signal to set on this request.
+   * Aborts the request when the signal fires.
+   * @type {(AbortSignal | undefined)}
+   */
+  get signal(): AbortSignal | undefined {
+    return this._signal;
+  }
+
+  set signal(value: AbortSignal | undefined) {
+    const old = this._signal;
+    if (old === value) {
+      return;
+    }
+    this._signal = value;
+    if (old) {
+      old.removeEventListener('abort', this._abortHandler);
+    }
+    if (value) {
+      value.addEventListener('abort', this._abortHandler);
+    }
+  }
+
+  /**
+   * Aborts the current run.
+   * The promise returned by the `execute()` method will reject if not yet resolved.
+   */
+  abort(): void {
+    this._state = State.Aborted;
+    const { workers } = this;
+    workers.forEach((info) => {
+      if (info.status !== 'error') {
+        try {
+          info.worker.destroy();
+        } catch (e) {
+          // ...
+        }
+        info.status = 'error';
+      }
+    });
+    if (this.mainRejecter) {
+      this.mainRejecter!(new Error(`The execution has been aborted.`));
+      this.mainRejecter = undefined;
+      this.mainResolver = undefined;
+    }
+  }
+
+  /**
+   * Handler for the `abort` event on the `AbortSignal`.
+   */
+  protected _abortHandler(): void {
+    this.abort();
+  }
+
   private _execute(): void {
+    this._state = State.Running as State;
     try {
       cluster.setupPrimary({
         exec: join(__dirname, 'ProjectRunnerWorker.js'),
@@ -105,6 +173,9 @@ export class ProjectParallelRunner extends BaseRunner {
     } catch (e) {
       const cause = e as Error;
       this.mainRejecter!(cause);
+      this.mainResolver = undefined
+      this.mainRejecter = undefined
+      this._state = State.Idle as State;
     }
   }
 
@@ -211,7 +282,10 @@ export class ProjectParallelRunner extends BaseRunner {
     this.endTime = Date.now();
     const report = await this.createReport();
     this.mainResolver(report);
+    this.mainResolver = undefined
+    this.mainRejecter = undefined
     cluster.off('exit', this._exitHandler);
+    this._state = State.Idle as State;
   }
 
   private setRunError(worker: Worker, message: IWorkerMessage): void {

package/src/runtime/node/ProjectRequestRunner.ts

@@ -14,6 +14,7 @@ import { VariablesProcessor } from '../variables/VariablesProcessor.js';
 import { RequestFactory } from './RequestFactory.js';
 import { EventTypes } from '../../events/EventTypes.js';
 import { ProjectRunnerOptions, ProjectRunnerRunOptions, RunResult } from './InteropInterfaces.js';
+import { State } from './enums.js';
 
 export interface ProjectRequestRunner {
   /**
@@ -62,6 +63,12 @@ export class ProjectRequestRunner extends EventEmitter {
    */
   protected variablesProcessor = new VariablesProcessor();
 
+  protected _state: State = State.Idle;
+
+  get state(): State {
+    return this._state;
+  }
+
   constructor(project: HttpProject, opts: ProjectRunnerOptions = {}) {
     super();
     this.project = project;
@@ -77,15 +84,25 @@ export class ProjectRequestRunner extends EventEmitter {
    * @returns A promise with the run result.
    */
   async run(options?: ProjectRunnerRunOptions): Promise<RunResult[]> {
+    this._state = State.Running as State;
     const { project } = this;
     const executed: RunResult[] = [];
     for (const request of project.requestIterator(options)) {
       const info = await this._runItem(request);
       executed.push(info);
     }
+    this._state = State.Idle;
     return executed;
   }
 
+  /**
+   * Aborts the current run.
+   * The promise returned by the `run()` method will reject if not yet resolved.
+   */
+  abort(): void {
+    this._state = State.Aborted;
+  }
+
   /**
    * Allows to iterate over project requests recursively and execute each request
    * in order. The generator yields the `RunResult` for the request.
@@ -101,13 +118,18 @@ export class ProjectRequestRunner extends EventEmitter {
    */
   async* [Symbol.asyncIterator](): AsyncGenerator<RunResult> {
     const { project } = this;
+    this._state = State.Running as State;
     for (const request of project.requestIterator({ recursive: true })) {
       const info = await this._runItem(request);
       yield info;
     }
+    this._state = State.Idle;
   }
 
   private async _runItem(request: ProjectRequest): Promise<RunResult> {
+    if (this._state === State.Aborted) {
+      throw new Error(`The execution has been aborted.`);
+    }
     const folder = request.getParent();
     const parent = folder || this.project;
     let variables: Record<string, string>;