@flow-conductor/core 1.0.0

package/build/index.js

@@ -0,0 +1,667 @@
+// src/utils/url-validator.ts
+var SSRFError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SSRFError";
+  }
+};
+var PRIVATE_IP_RANGES = [
+  // IPv4 private ranges
+  /^10\./,
+  /^172\.(1[6-9]|2[0-9]|3[01])\./,
+  /^192\.168\./,
+  // IPv6 private ranges
+  /^fc00:/i,
+  /^fe80:/i,
+  /^::1$/,
+  /^fd/
+];
+function validateUrl(url, options = {}) {
+  const {
+    allowPrivateIPs = false,
+    allowLocalhost = false,
+    allowedProtocols = ["http:", "https:"],
+    disableValidation = false
+  } = options;
+  if (disableValidation) {
+    return;
+  }
+  if (!url || typeof url !== "string") {
+    throw new SSRFError("URL must be a non-empty string");
+  }
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(url);
+  } catch {
+    throw new SSRFError(`Invalid URL format: ${url}`);
+  }
+  const protocol = parsedUrl.protocol.toLowerCase();
+  if (!allowedProtocols.includes(protocol)) {
+    throw new SSRFError(
+      `Protocol "${protocol}" is not allowed. Only ${allowedProtocols.join(", ")} are permitted.`
+    );
+  }
+  const hostname = parsedUrl.hostname.toLowerCase();
+  const normalizedHostname = hostname.replace(/^\[|\]$/g, "");
+  const isLocalhost = normalizedHostname === "localhost" || normalizedHostname === "127.0.0.1" || normalizedHostname === "::1" || normalizedHostname.startsWith("127.") || normalizedHostname === "0.0.0.0";
+  if (isLocalhost && !allowLocalhost) {
+    throw new SSRFError(
+      "Localhost addresses are not allowed for security reasons. Set allowLocalhost=true to override."
+    );
+  }
+  if (!allowPrivateIPs) {
+    if (/^\d+\.\d+\.\d+\.\d+$/.test(normalizedHostname)) {
+      const parts = normalizedHostname.split(".").map(Number);
+      const [a, b] = parts;
+      if (a === 10) {
+        throw new SSRFError(
+          "Private IP addresses (10.x.x.x) are not allowed for security reasons."
+        );
+      }
+      if (a === 172 && b >= 16 && b <= 31) {
+        throw new SSRFError(
+          "Private IP addresses (172.16-31.x.x) are not allowed for security reasons."
+        );
+      }
+      if (a === 192 && b === 168) {
+        throw new SSRFError(
+          "Private IP addresses (192.168.x.x) are not allowed for security reasons."
+        );
+      }
+      if (a === 169 && b === 254) {
+        throw new SSRFError(
+          "Link-local addresses (169.254.x.x) are not allowed for security reasons."
+        );
+      }
+    }
+    const isPrivateIP = PRIVATE_IP_RANGES.some(
+      (range) => range.test(normalizedHostname)
+    );
+    if (isPrivateIP) {
+      throw new SSRFError(
+        "Private/internal IP addresses are not allowed for security reasons. Set allowPrivateIPs=true to override."
+      );
+    }
+  }
+}
+
+// src/request-adapter.ts
+var RequestAdapter = class {
+  /**
+   * Creates a new RequestAdapter instance.
+   *
+   * @param urlValidationOptions - Options for URL validation to prevent SSRF attacks
+   */
+  constructor(urlValidationOptions = {}) {
+    this.urlValidationOptions = urlValidationOptions;
+  }
+  /**
+   * Type-safe getter for the execution result.
+   * Allows casting the result to a specific type.
+   *
+   * @template T - The desired result type
+   * @param result - The execution result to cast
+   * @returns The result cast to type T
+   */
+  getResult(result) {
+    return result;
+  }
+  /**
+   * Executes a request with URL validation.
+   * Validates the URL to prevent SSRF attacks before creating the request.
+   *
+   * @param requestConfig - The request configuration object
+   * @returns A promise that resolves to the execution result
+   * @throws {SSRFError} If the URL is invalid or potentially dangerous
+   */
+  executeRequest(requestConfig) {
+    validateUrl(requestConfig.url, this.urlValidationOptions);
+    return this.createRequest(requestConfig);
+  }
+};
+
+// src/request-manager.ts
+var RequestFlow = class {
+  constructor() {
+    /**
+     * List of pipeline stages to execute
+     */
+    this.requestList = [];
+  }
+  /**
+   * Sets the request adapter to use for executing HTTP requests.
+   *
+   * @param adapter - The request adapter instance
+   * @returns The current RequestFlow instance for method chaining
+   */
+  setRequestAdapter(adapter) {
+    this.adapter = adapter;
+    return this;
+  }
+  /**
+   * Adds multiple pipeline stages to the request list.
+   *
+   * @param requestList - Array of pipeline stages to add
+   * @returns The current RequestFlow instance for method chaining
+   */
+  addAll(requestList = []) {
+    this.requestList = this.requestList.concat(requestList);
+    return this;
+  }
+  /**
+   * Sets an error handler callback that will be called when an error occurs during execution.
+   *
+   * @param errorHandler - Function to handle errors
+   * @returns The current RequestFlow instance for method chaining
+   */
+  withErrorHandler(errorHandler) {
+    this.errorHandler = errorHandler;
+    return this;
+  }
+  /**
+   * Sets a result handler callback that will be called with the execution result.
+   *
+   * @param resultHandler - Function to handle results
+   * @returns The current RequestFlow instance for method chaining
+   */
+  withResultHandler(resultHandler) {
+    this.resultHandler = resultHandler;
+    return this;
+  }
+  /**
+   * Sets a finish handler callback that will be called after execution completes (success or failure).
+   *
+   * @param finishHandler - Function to execute on completion
+   * @returns The current RequestFlow instance for method chaining
+   */
+  withFinishHandler(finishHandler) {
+    this.finishHandler = finishHandler;
+    return this;
+  }
+};
+
+// src/utils/retry-utils.ts
+function getErrorStatus(error) {
+  if (typeof error.response !== "undefined" && typeof error.response.status === "number") {
+    return error.response.status;
+  }
+  if (typeof error.status === "number") {
+    return error.status;
+  }
+  if (typeof error.statusCode === "number") {
+    return error.statusCode;
+  }
+  return void 0;
+}
+function isNetworkError(error) {
+  const networkErrorNames = [
+    "TypeError",
+    "NetworkError",
+    "TimeoutError",
+    "AbortError",
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "ETIMEDOUT"
+  ];
+  if (networkErrorNames.includes(error.name)) {
+    return true;
+  }
+  const networkKeywords = [
+    "network",
+    "connection",
+    "timeout",
+    "fetch",
+    "failed to fetch",
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "ETIMEDOUT"
+  ];
+  const errorMessage = error.message?.toLowerCase() || "";
+  return networkKeywords.some((keyword) => errorMessage.includes(keyword));
+}
+function defaultRetryCondition(error) {
+  return isNetworkError(error);
+}
+function retryOnStatusCodes(...statusCodes) {
+  return (error) => {
+    const status = getErrorStatus(error);
+    return status !== void 0 && statusCodes.includes(status);
+  };
+}
+function retryOnNetworkOrStatusCodes(...statusCodes) {
+  return (error) => {
+    if (isNetworkError(error)) {
+      return true;
+    }
+    const status = getErrorStatus(error);
+    return status !== void 0 && statusCodes.includes(status);
+  };
+}
+
+// src/utils/chunk-processor.ts
+async function processStream(stream, config) {
+  const { chunkHandler, encoding = "utf-8", accumulate = false } = config;
+  const reader = stream.getReader();
+  const decoder = new TextDecoder(encoding);
+  let accumulatedData;
+  let chunkIndex = 0;
+  let totalBytesRead = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        if (accumulatedData !== void 0 && accumulatedData.length > 0) {
+          await processChunk(
+            accumulatedData,
+            chunkHandler,
+            chunkIndex,
+            true,
+            totalBytesRead
+          );
+        }
+        break;
+      }
+      totalBytesRead += value.length;
+      if (accumulate) {
+        if (accumulatedData === void 0) {
+          accumulatedData = value;
+        } else if (typeof accumulatedData === "string") {
+          accumulatedData += decoder.decode(value, { stream: true });
+        } else {
+          const combined = new Uint8Array(
+            accumulatedData.length + value.length
+          );
+          combined.set(accumulatedData);
+          combined.set(value, accumulatedData.length);
+          accumulatedData = combined;
+        }
+      }
+      const isLast = false;
+      await processChunk(
+        value,
+        chunkHandler,
+        chunkIndex,
+        isLast,
+        totalBytesRead
+      );
+      chunkIndex++;
+    }
+    return accumulatedData;
+  } finally {
+    reader.releaseLock();
+  }
+}
+async function processTextStreamLineByLine(stream, config) {
+  const { chunkHandler, encoding = "utf-8", accumulate = false } = config;
+  const reader = stream.getReader();
+  const decoder = new TextDecoder(encoding);
+  let buffer = "";
+  let lineIndex = 0;
+  let totalBytesRead = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        if (buffer.length > 0) {
+          await processChunk(
+            buffer,
+            chunkHandler,
+            lineIndex,
+            true,
+            totalBytesRead
+          );
+        }
+        break;
+      }
+      totalBytesRead += value.length;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      for (const line of lines) {
+        if (line.length > 0) {
+          await processChunk(
+            line,
+            chunkHandler,
+            lineIndex,
+            false,
+            totalBytesRead
+          );
+          lineIndex++;
+        }
+      }
+    }
+    return accumulate ? buffer : void 0;
+  } finally {
+    reader.releaseLock();
+  }
+}
+async function processResponseStream(response, config) {
+  if (!response.body) {
+    throw new Error("Response body is not available for streaming");
+  }
+  const processed = await processStream(response.body, config);
+  if (config.accumulate && processed !== void 0) {
+    return processed;
+  }
+  return response;
+}
+async function processChunk(chunk, handler, index, isLast, totalBytesRead) {
+  const result = handler(chunk, {
+    index,
+    isLast,
+    totalBytesRead
+  });
+  if (result instanceof Promise) {
+    await result;
+  }
+}
+function isReadableStream(value) {
+  return value !== null && typeof value === "object" && "getReader" in value && typeof value.getReader === "function";
+}
+function hasReadableStream(response) {
+  return response.body !== null && isReadableStream(response.body);
+}
+
+// src/request-chain.ts
+var _RequestChain = class _RequestChain extends RequestFlow {
+  constructor() {
+    super(...arguments);
+    /**
+     * Adds a new stage to the request chain and returns a new chain with updated types.
+     * This method enables type-safe chaining of requests.
+     *
+     * @template NewOut - The output type of the new stage
+     * @param stage - The pipeline stage to add (request or manager stage)
+     * @returns A new RequestChain instance with the added stage
+     */
+    this.next = (stage) => {
+      return this.addRequestEntity(stage);
+    };
+    /**
+     * Executes all stages in the chain sequentially and returns the final result.
+     * Handles errors and calls registered handlers appropriately.
+     *
+     * @returns A promise that resolves to the final output result
+     * @throws {Error} If an error occurs and no error handler is registered
+     */
+    this.execute = async () => {
+      try {
+        const results = await this.executeAllRequests(this.requestList);
+        const result = results[results.length - 1];
+        if (this.resultHandler && result) {
+          this.resultHandler(result);
+        }
+        return result;
+      } catch (error) {
+        if (this.errorHandler) {
+          this.errorHandler(error);
+          return Promise.reject(error);
+        } else {
+          throw error;
+        }
+      } finally {
+        if (this.finishHandler) {
+          this.finishHandler();
+        }
+      }
+    };
+    //  #endregion
+    //  #region Private methods
+    /**
+     * Adds a request entity (stage) to the internal request list.
+     *
+     * @template NewOut - The output type of the new stage
+     * @param stage - The pipeline stage to add
+     * @returns A new RequestChain instance with updated types
+     */
+    this.addRequestEntity = (stage) => {
+      this.requestList.push(stage);
+      return this;
+    };
+    /**
+     * Executes all request entities in sequence, handling preconditions and mappers.
+     * Stages with failed preconditions are skipped but preserve the previous result.
+     *
+     * @template Out - The output type
+     * @param requestEntityList - List of pipeline stages to execute
+     * @returns A promise that resolves to an array of all stage results
+     */
+    this.executeAllRequests = async (requestEntityList) => {
+      const results = [];
+      for (let i = 0; i < requestEntityList.length; i++) {
+        const requestEntity = requestEntityList[i];
+        if (requestEntity.precondition && !requestEntity.precondition()) {
+          const previousEntity2 = requestEntityList[i - 1];
+          const previousResult2 = previousEntity2?.result;
+          requestEntityList[i].result = previousResult2;
+          continue;
+        }
+        const previousEntity = requestEntityList[i - 1];
+        const previousResult = previousEntity?.result;
+        try {
+          const requestResult = await this.executeSingle(
+            requestEntity,
+            previousResult
+          );
+          let result = requestResult;
+          if (requestEntity.mapper) {
+            let mappedResult;
+            if (isPipelineRequestStage(requestEntity)) {
+              mappedResult = requestEntity.mapper(
+                requestResult,
+                previousResult
+              );
+            } else if (isPipelineManagerStage(requestEntity)) {
+              mappedResult = requestEntity.mapper(
+                requestResult,
+                previousResult
+              );
+            } else {
+              mappedResult = result;
+            }
+            result = mappedResult instanceof Promise ? await mappedResult : mappedResult;
+          }
+          if (requestEntity.resultInterceptor) {
+            await requestEntity.resultInterceptor(result);
+          }
+          requestEntityList[i].result = result;
+          results.push(result);
+        } catch (error) {
+          const requestConfig = isPipelineRequestStage(requestEntity) ? requestEntity.config : void 0;
+          error.cause = { ...error.cause, requestConfig };
+          if (requestEntity.errorHandler) {
+            await requestEntity.errorHandler(error);
+          }
+          throw error;
+        }
+      }
+      return results;
+    };
+    /**
+     * Executes a single request entity (stage).
+     * Handles both request stages and nested manager stages.
+     * Implements retry logic for request stages when retry configuration is provided.
+     * Supports progressive chunk processing for streaming responses.
+     *
+     * @template Out - The output type
+     * @param requestEntity - The pipeline stage to execute
+     * @param previousResult - The result from the previous stage (optional)
+     * @returns A promise that resolves to the stage result
+     * @throws {Error} If the stage type is unknown or all retries are exhausted
+     */
+    this.executeSingle = async (requestEntity, previousResult) => {
+      if (isPipelineRequestStage(requestEntity)) {
+        const { config, retry, chunkProcessing } = requestEntity;
+        const requestConfig = typeof config === "function" ? config(previousResult) : config;
+        if (retry) {
+          return this.executeWithRetry(
+            requestConfig,
+            retry,
+            chunkProcessing
+          );
+        }
+        const rawResult = await this.adapter.executeRequest(requestConfig);
+        return this.processResultWithChunks(rawResult, chunkProcessing);
+      } else if (isPipelineManagerStage(requestEntity)) {
+        const { request } = requestEntity;
+        const rawResult = await request.execute();
+        return rawResult;
+      } else {
+        throw new Error("Unknown type");
+      }
+    };
+    /**
+     * Executes a request with retry logic based on the provided retry configuration.
+     * Supports chunk processing for streaming responses.
+     *
+     * @template Out - The output type
+     * @param requestConfig - The request configuration
+     * @param retryConfig - The retry configuration
+     * @param chunkProcessing - Optional chunk processing configuration
+     * @returns A promise that resolves to the request result
+     * @throws {Error} If all retry attempts are exhausted
+     */
+    this.executeWithRetry = async (requestConfig, retryConfig, chunkProcessing) => {
+      const maxRetries = retryConfig.maxRetries ?? 3;
+      const retryCondition = retryConfig.retryCondition ?? defaultRetryCondition;
+      let lastError;
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          const rawResult = await this.adapter.executeRequest(requestConfig);
+          return this.processResultWithChunks(rawResult, chunkProcessing);
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+          const shouldRetry = attempt < maxRetries && retryCondition(lastError, attempt);
+          if (!shouldRetry) {
+            throw lastError;
+          }
+          const delay = this.calculateRetryDelay(
+            attempt + 1,
+            lastError,
+            retryConfig
+          );
+          if (delay > 0) {
+            await this.sleep(delay);
+          }
+        }
+      }
+      throw lastError || new Error("Retry failed");
+    };
+    /**
+     * Processes a result with chunk processing if enabled.
+     * Handles streaming responses by processing chunks progressively.
+     *
+     * @template Out - The output type
+     * @param rawResult - The raw result from the adapter
+     * @param chunkProcessing - Optional chunk processing configuration
+     * @returns A promise that resolves to the processed result
+     */
+    this.processResultWithChunks = async (rawResult, chunkProcessing) => {
+      if (chunkProcessing?.enabled && rawResult instanceof Response && hasReadableStream(rawResult)) {
+        const clonedResponse = rawResult.clone();
+        const processed = await processResponseStream(clonedResponse, {
+          ...chunkProcessing
+        });
+        if (chunkProcessing.accumulate && processed !== rawResult) {
+          return processed;
+        }
+        return this.adapter.getResult(rawResult);
+      }
+      return this.adapter.getResult(rawResult);
+    };
+  }
+  /**
+   * Executes all stages in the chain and returns all results as a tuple.
+   * Useful when you need access to intermediate results.
+   *
+   * @returns A promise that resolves to a tuple of all stage results
+   * @throws {Error} If an error occurs and no error handler is registered
+   */
+  async executeAll() {
+    try {
+      const results = await this.executeAllRequests(this.requestList);
+      if (this.resultHandler && results.length > 0) {
+        this.resultHandler(results);
+      }
+      return results;
+    } catch (error) {
+      if (this.errorHandler) {
+        this.errorHandler(error);
+        return Promise.reject(error);
+      } else {
+        throw error;
+      }
+    } finally {
+      if (this.finishHandler) {
+        this.finishHandler();
+      }
+    }
+  }
+  /**
+   * Calculates the delay before the next retry attempt.
+   *
+   * @param attempt - The current attempt number (1-indexed for retries)
+   * @param error - The error that occurred
+   * @param retryConfig - The retry configuration
+   * @returns The delay in milliseconds
+   */
+  calculateRetryDelay(attempt, error, retryConfig) {
+    const baseDelay = retryConfig.retryDelay ?? 1e3;
+    const maxDelay = retryConfig.maxDelay;
+    let delay;
+    if (typeof baseDelay === "function") {
+      delay = baseDelay(attempt, error);
+    } else if (retryConfig.exponentialBackoff) {
+      delay = baseDelay * Math.pow(2, attempt - 1);
+      if (maxDelay !== void 0 && delay > maxDelay) {
+        delay = maxDelay;
+      }
+    } else {
+      delay = baseDelay;
+    }
+    return Math.max(0, delay);
+  }
+  /**
+   * Sleeps for the specified number of milliseconds.
+   *
+   * @param ms - Milliseconds to sleep
+   * @returns A promise that resolves after the delay
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  //  #endregion
+};
+//  #region Public methods
+/**
+ * Creates a new RequestChain with an initial stage.
+ * This is the entry point for building a request chain.
+ *
+ * @template Out - The output type of the initial stage
+ * @template AdapterExecutionResult - The type of result returned by the adapter
+ * @template AdapterRequestConfig - The type of request configuration
+ * @param stage - The initial pipeline stage (request or manager stage)
+ * @param adapter - The request adapter to use for HTTP requests
+ * @returns A new RequestChain instance with the initial stage
+ */
+_RequestChain.begin = (stage, adapter) => {
+  const requestChain = new _RequestChain();
+  requestChain.setRequestAdapter(adapter);
+  return requestChain.next(stage);
+};
+var RequestChain = _RequestChain;
+function begin(stage, adapter) {
+  const requestChain = new RequestChain();
+  requestChain.setRequestAdapter(adapter);
+  return requestChain.next(stage);
+}
+function isPipelineRequestStage(stage) {
+  return "config" in stage && !("request" in stage);
+}
+function isPipelineManagerStage(stage) {
+  return "request" in stage && !("config" in stage);
+}
+
+export { RequestAdapter, RequestChain, RequestFlow as RequestManager, SSRFError, begin, RequestChain as default, defaultRetryCondition, getErrorStatus, hasReadableStream, isNetworkError, isReadableStream, processResponseStream, processStream, processTextStreamLineByLine, retryOnNetworkOrStatusCodes, retryOnStatusCodes, validateUrl };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map