Architecture

A look under the hood at how Overload is structured.

System Overview

Overload is primarily built in Python, leveraging modern asyncio primitives for high-concurrency network I/O. The project is split into four main subsystems:

  1. Collection Parser: Translates Postman JSON into internal dataclasses.
  2. Load Engine: Asynchronously dispatches HTTP requests using specific concurrency patterns.
  3. Reporting: Aggregates metrics and generates HTML/JSON/CSV outputs.
  4. Web UI: A FastAPI server wrapping the engine, communicating with a Vanilla JS frontend via REST and WebSockets.

The Async Engine

The core of Overload is the HttpClient (wrapping httpx.AsyncClient) and the LoadPattern protocol.

Instead of relying on threads or multiple processes, Overload uses Python's asyncio event loop. This allows a single process to handle thousands of concurrent HTTP connections efficiently.

Each load test pattern implements the LoadPattern protocol:

class LoadPattern(Protocol):
    async def execute(self, client, requests, variables, config, run_id, cancel_event, on_progress) -> list[RequestResult]

Depending on the pattern (e.g., Burst vs. Load), tasks are either spawned all at once using an asyncio.Semaphore to limit concurrency, or dispatched iteratively on a strict 1-second interval to achieve a precise RPS curve.

Variable Resolution

Variables are resolved just-in-time, right before an HTTP request is dispatched. The VariableContext class manages a 3-tier scope (Runtime, Environment, Collection). It recursively parses the request URL, headers, and body, searching for the {{var}} regex and substituting values securely.

Web Architecture

When you run overload ui, a Uvicorn/FastAPI server is launched locally.