curl-runner-core
Version:
Core library for running cURL scripts with comprehensive logging, error handling, and parallel execution capabilities. Zero external dependencies for maximum security.
595 lines (568 loc) • 34.5 kB
Plain Text
# Execution Flow Diagrams
This document contains ASCII flow diagrams for understanding how curl-runner-core executes scripts in different modes.
## Sequential Execution Flow
Sequential execution runs scripts one at a time, waiting for each to complete before starting the next.
```
┌─────┐
│Start│
└──┬──┘
│
▼
┌──────────────────┐
│Scan Scripts Dir │
└──┬───────────────┘
│
▼
┌──────────────┐
│Scripts Found?│
└──┬───────────┘
│
├─── No ───► ┌─────────────────┐
│ │Return Empty Array│
│ └─────────────────┘
│
└─── Yes ───► ┌──────────────┐
│Create Log File│
└──┬───────────┘
│
▼
┌─────────────────────┐
│Initialize Results [] │
└──┬──────────────────┘
│
▼
┌──────────────┐
│For Each Script│
└──┬───────────┘
│
▼
┌──────────────┐
│Execute Script│
└──┬───────────┘
│
▼
┌─────────────────┐
│Wait for Complete│
└──┬──────────────┘
│
▼
┌──────────────┐
│Parse Output │
└──┬───────────┘
│
▼
┌──────────────┐
│Log Result │
└──┬───────────┘
│
▼
┌──────────────┐
│More Scripts? │
└──┬───────────┘
│
├─── Yes ───┐
│ │
└─── No ────►│
▼
┌──────────────┐
│Generate Summary│
└──┬───────────┘
│
▼
┌──────────────┐
│Write Report │
└──┬───────────┘
│
▼
┌──────────────┐
│Return Results│
└──┬───────────┘
│
▼
┌─────┐
│ End │
└─────┘
```
**Description**: The system scans the scripts directory, creates a log file, then processes each script sequentially. Each script must complete before the next begins. Results are collected and a summary is generated at the end.
## Parallel Execution Flow
Parallel execution runs all scripts simultaneously for maximum speed.
```
┌─────┐
│Start│
└──┬──┘
│
▼
┌──────────────────┐
│Scan Scripts Dir │
└──┬───────────────┘
│
▼
┌──────────────┐
│Scripts Found?│
└──┬───────────┘
│
├─── No ───► ┌─────────────────┐
│ │Return Empty Array│
│ └─────────────────┘
│
└─── Yes ───► ┌──────────────┐
│Create Log File│
└──┬───────────┘
│
▼
┌──────────────┐
│Start Timer │
└──┬───────────┘
│
▼
┌──────────────────┐
│Create Promise [] │
└──┬───────────────┘
│
▼
┌──────────────┐
│For Each Script│
└──┬───────────┘
│
▼
┌──────────────────┐
│Execute Async │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Add Promise to [] │
└──┬───────────────┘
│
▼
┌──────────────┐
│More Scripts? │
└──┬───────────┘
│
├─── Yes ───┐
│ │
└─── No ───►│
▼
┌──────────────────┐
│Promise.all Wait │
└──┬───────────────┘
│
▼
┌──────────────────┐
│All Scripts Done │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Calculate Duration │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Parse All Results │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Generate Summary │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Write Report Log │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Return Results │
└──┬───────────────┘
│
▼
┌─────┐
│ End │
└─────┘
```
**Description**: All scripts are started simultaneously using JavaScript's Promise.all. While scripts wait for network I/O, the event loop allows other scripts to make progress. The system waits for all promises to resolve, then collects results and generates a summary.
## Concurrent Execution Flow
Concurrent execution runs scripts in controlled batches with configurable delays.
```
┌─────┐
│Start│
└──┬──┘
│
▼
┌──────────────────┐
│Scan Scripts Dir │
└──┬───────────────┘
│
▼
┌──────────────┐
│Scripts Found?│
└──┬───────────┘
│
├─── No ───► ┌─────────────────┐
│ │Return Empty Array│
│ └─────────────────┘
│
└─── Yes ───► ┌──────────────┐
│Create Log File│
└──┬───────────┘
│
▼
┌──────────────────┐
│Calculate Batches │
└──┬───────────────┘
│
▼
┌──────────────┐
│Start Timer │
└──┬───────────┘
│
▼
┌──────────────┐
│For Each Batch│
└──┬───────────┘
│
▼
┌──────────────────┐
│Create Batch [] │
└──┬───────────────┘
│
▼
┌──────────────────┐
│For Each in Batch │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Execute Async │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Add to Batch [] │
└──┬───────────────┘
│
▼
┌──────────────┐
│More in Batch?│
└──┬───────────┘
│
├─── Yes ───┐
│ │
└─── No ───►│
▼
┌──────────────────┐
│Promise.all Batch │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Batch Complete │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Log Batch Results │
└──┬───────────────┘
│
▼
┌──────────────┐
│More Batches? │
└──┬───────────┘
│
├─── Yes ───► ┌──────────────┐
│ │Wait Delay │
│ └──┬───────────┘
│ │
│ └──┐
│ │
└─── No ───────────┘
│
▼
┌──────────────────┐
│Calculate Duration│
└──┬───────────────┘
│
▼
┌──────────────────┐
│Generate Summary │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Write Report Log │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Return All Results│
└──┬───────────────┘
│
▼
┌─────┐
│ End │
└─────┘
```
**Description**: Scripts are divided into batches. Each batch runs in parallel, but batches execute sequentially with an optional delay between them. This provides a balance between speed and resource usage.
## Single Script Execution Flow
Individual script execution with error handling and logging.
```
┌─────┐
│Start│
└──┬──┘
│
▼
┌──────────────────┐
│Validate Script │
└──┬───────────────┘
│
▼
┌──────────────┐
│Script Exists?│
└──┬───────────┘
│
├─── No ───► ┌──────────────────┐
│ │Return Error Result│
│ └──┬────────────────┘
│ │
│ └──► ┌─────┐
│ │ End │
│ └─────┘
│
└─── Yes ───► ┌──────────────┐
│Create Log File│
└──┬───────────┘
│
▼
┌──────────────┐
│Start Timer │
└──┬───────────┘
│
▼
┌──────────────────┐
│Execute bash Script│
└──┬───────────────┘
│
▼
┌──────────────┐
│Execution Err?│
└──┬───────────┘
│
├─── Yes ───► ┌──────────────┐
│ │Log Error │
│ └──┬───────────┘
│ │
│ ▼
│ ┌──────────────────┐
│ │Write Error Log │
│ └──┬───────────────┘
│ │
│ ▼
│ ┌──────────────────┐
│ │Return Error Result│
│ └──┬───────────────┘
│ │
│ └──► ┌─────┐
│ │ End │
│ └─────┘
│
└─── No ───► ┌──────────────────┐
│Parse cURL Output │
└──┬───────────────┘
│
▼
┌──────────────┐
│HTTP Error? │
└──┬───────────┘
│
├─── Yes ───► ┌──────────────┐
│ │Log API Error │
│ └──┬───────────┘
│ │
│ ▼
│ ┌──────────────────┐
│ │Write Error Log │
│ └──┬───────────────┘
│ │
│ ▼
│ ┌──────────────────┐
│ │Return Error Result│
│ └──┬───────────────┘
│ │
│ └──► ┌─────┐
│ │ End │
│ └─────┘
│
└─── No ───► ┌──────────────┐
│Log Success │
└──┬───────────┘
│
▼
┌──────────────────┐
│Write Report Log │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Calculate Duration│
└──┬───────────────┘
│
▼
┌──────────────────┐
│Return Success │
└──┬───────────────┘
│
▼
┌─────┐
│ End │
└─────┘
```
**Description**: A single script is validated, executed, and its output is parsed. Errors are categorized as execution errors or HTTP errors, and appropriate logs are written. The result includes success status, duration, HTTP status, and any error messages.
## System Architecture
Overall system architecture showing component relationships.
```
┌─────────────────────────────────────────────────────────────┐
│ User Interface │
│ │
│ ┌──────────────────┐ ┌──────────────────────┐ │
│ │Programmatic API │────────►│Convenience Functions │ │
│ └──────────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Core Engine │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ CurlRunner Class │ │
│ └──┬───────────────────────────────────────────────────┘ │
│ │ │
│ ├──► ┌──────────────────┐ │
│ │ │Script Execution │ │
│ │ └──────────────────┘ │
│ │ │
│ ├──► ┌──────────────────┐ │
│ │ │Logging System │ │
│ │ └──────────────────┘ │
│ │ │
│ └──► ┌──────────────────┐ │
│ │Parser System │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Execution Modes │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Sequential │ │ Parallel │ │ Concurrent │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Utilities │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ CurlParser │ │ Logger │ │ FileSystem │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Output │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │Results Array │ │ Report Log │ │ Error Log │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ │
│ │ Log Files │ │
│ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
**Description**: The system is organized into layers. Users interact through convenience functions or the CurlRunner class directly. The core engine handles execution, logging, and parsing. Execution can occur in three modes, all producing results that are logged to various output files.
## Error Handling Flow
Error detection and logging process.
```
┌──────────────────┐
│Script Execution │
└──┬───────────────┘
│
▼
┌──────────────┐
│Exec Success? │
└──┬───────────┘
│
├─── No ───► ┌──────────────┐
│ │Capture Error │
│ └──┬───────────┘
│ │
│ ▼
│ ┌──────────────┐
│ │Error Type? │
│ └──┬───────────┘
│ │
│ ├─── Exec Error ───► ┌──────────────────┐
│ │ │Log to Error Log │
│ │ └──┬───────────────┘
│ │ │
│ ├─── HTTP 4xx/5xx ───► ┌──────────────────┐
│ │ │Parse HTTP Status │
│ │ └──┬───────────────┘
│ │ │
│ │ ▼
│ │ ┌──────────────────┐
│ │ │Log to API Err Log│
│ │ └──┬───────────────┘
│ │ │
│ └─── Network Error ───► ┌──────────────────┐
│ │Log to Error Log │
│ └──┬───────────────┘
│ │
│ ▼
│ ┌──────────────────┐
│ │Return Error Result│
│ └──┬───────────────┘
│ │
│ └──┐
│ │
└─── Yes ──────────────────────────────────────┘
│
▼
┌──────────────┐
│Parse Output │
└──┬───────────┘
│
▼
┌──────────────┐
│HTTP Status? │
└──┬───────────┘
│
├─── 2xx ───► ┌──────────────────┐
│ │Success Result │
│ └──┬───────────────┘
│ │
├─── 4xx/5xx ─► ┌──────────────────┐
│ │API Error Result │
│ └──┬───────────────┘
│ │
└─── No Status ───►│
│
▼
┌──────────────────┐
│Log Success/Error │
└──┬───────────────┘
│
▼
┌──────────────────┐
│Return Result │
└──┬───────────────┘
│
▼
┌─────┐
│ End │
└─────┘
```
**Description**: Errors are detected at multiple stages. Execution errors occur when the script fails to run. HTTP errors are detected by parsing status codes from the output. Network errors are caught during execution. All errors are logged appropriately and included in the result object.