Add framework to measure code base performance ✨ 💎 (#558)

- Add framework to measure code base performance. This is to refactor more comfortably Cython code and core features, keeping an eye on performance.
- Download the `benchmark-reports` artifact from the GitHub Workflow to see it in action. https://github.com/Neoteroi/BlackSheep/actions/runs/14950087869

Author: RobertoPrevato

.github/workflows/perf.yml

@@ -0,0 +1,110 @@
+####################################################################################
+# Runs benchmarks for BlackSheep source code for various versions of Python
+# and Operating System and publishes the results.
+# See the perf folder for more information.
+####################################################################################
+name: Benchmark
+
+on:
+  push:
+    paths:
+      - 'perf/**'
+  workflow_dispatch:
+
+jobs:
+  perf-tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 9
+          submodules: false
+
+      - name: Use Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install flake8
+
+      - name: Compile Cython extensions
+        run: |
+          cython blacksheep/url.pyx
+          cython blacksheep/exceptions.pyx
+          cython blacksheep/headers.pyx
+          cython blacksheep/cookies.pyx
+          cython blacksheep/contents.pyx
+          cython blacksheep/messages.pyx
+          cython blacksheep/scribe.pyx
+          cython blacksheep/baseapp.pyx
+          python setup.py build_ext --inplace
+
+      - name: Install dependencies for benchmark
+        run: |
+          cd perf
+          pip install -r req.txt
+
+      - name: Run benchmark
+        shell: bash
+        run: |
+          export PYTHONPATH="."
+          python perf/main.py --times 5
+
+      - name: Upload results
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results-${{ matrix.os }}-${{ matrix.python-version }}
+          path: benchmark_results
+
+  genreport:
+    runs-on: ubuntu-latest
+    needs: [perf-tests]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 9
+          submodules: false
+
+      - name: Download a distribution artifact
+        uses: actions/download-artifact@v4
+        with:
+          pattern: benchmark-results-*
+          merge-multiple: true
+          path: benchmark_results
+
+      - name: Use Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: |
+          cd perf
+          pip install -r req.txt
+
+      - name: Generate report
+        shell: bash
+        run: |
+          ls -R benchmark_results
+          chmod -R 755 benchmark_results
+
+          export PYTHONPATH="."
+          python perf/genreport.py
+          python perf/genreport.py --output windows-results.xlsx --platform Windows
+          python perf/genreport.py --output linux-results.xlsx --platform Linux
+          python perf/genreport.py --output macos-results.xlsx --platform macOS
+
+      - name: Upload reports
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-reports
+          path: "**/*.xlsx"  # Upload all .xlsx files

.gitignore

@@ -128,3 +128,6 @@ nice-cat.jpg
 venv*
 
 .local/*
+benchmark_results/
+*.xlsx
+.~lock*

perf/README.md

@@ -0,0 +1,87 @@
+# Benchmark
+
+This folder contains scripts to benchmark the performance of the library. The
+purpose of these benchmarks is to measure how changes in code affect
+performance, across Git commits, Python versions, and operating system.
+
+Benchmarks measure execution time and memory utilization.
+
+> [!TIP]
+>
+> Download the results from the GitHub Workflow.
+> The `benchmark-reports` artifacts include Excel files with tables and charts.
+>
+>  [![Build](https://github.com/Neoteroi/BlackSheep/workflows/Benchmark/badge.svg)](https://github.com/Neoteroi/BlackSheep/actions/workflows/perf.yml)
+
+The code can both collect information and compare it depending on the Git
+commit SHA.
+
+```bash
+pip install -r req.txt
+```
+
+From the root folder:
+
+```bash
+# Run the benchmark suite
+export PYTHONPATH="."
+
+python perf/main.py
+
+# To run more than onces:
+python perf/main.py --times 3
+
+# Generate XLSX report
+python perf/genreport.py
+```
+
+Run to generate results from different points in history:
+
+```bash
+python perf/historyrun.py --commits 82ed065 1237b1e
+```
+
+## Code organization
+
+Benchmarks are organized in such way that each file can be run interactively using
+**iPython**, but are also automatically imported by `main.py` following the convention
+that benchmark functions have names starting with `benchmark_`.
+
+To run a single benchmark using **iPython**, or [`cProfile`](https://docs.python.org/3.13/library/profile.html#profile-cli):
+
+```bash
+export PYTHONPATH="."
+
+ipython perf/benchmarks/writeresponse.py timeit
+
+python -m cProfile -s tottime perf/benchmarks/writeresponse.py | head -n 50
+```
+
+## Debugging with Visual Studio Code
+
+To debug specific files with VS Code, use a `.vscode\launch.json` file like:
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}"
+            }
+        }
+    ]
+}
+```
+
+## When modifying benchmark code
+
+```bash
+export PYTHONPATH="."
+rm -rf benchmark_results && python perf/main.py && python perf/genreport.py
+```

perf/benchmarks/__init__.py

@@ -0,0 +1,93 @@
+import gc
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TypedDict
+
+
+class BenchmarkResult(TypedDict):
+    total_time: float
+    avg_time: float
+    iterations: int
+
+
+@dataclass
+class TimerResult:
+    elapsed_time: float
+
+
+@contextmanager
+def timer():
+    result = TimerResult(-1)
+    start_time = time.perf_counter()  # Use perf_counter for high-resolution timing
+    yield result
+    end_time = time.perf_counter()
+    result.elapsed_time = end_time - start_time
+
+
+async def async_benchmark(func, iterations: int) -> BenchmarkResult:
+    # warmup
+    warmup_iterations = max(1, min(100, iterations // 10))
+    for _ in range(warmup_iterations):
+        await func()
+
+    # Collect garbage to ensure fair comparison
+    gc.collect()
+
+    # actual timing
+    with timer() as result:
+        for _ in range(iterations):
+            await func()
+
+    return {
+        "total_time": result.elapsed_time,
+        "avg_time": result.elapsed_time / iterations,
+        "iterations": iterations,
+    }
+
+
+def sync_benchmark(func, iterations: int) -> BenchmarkResult:
+    # warmup
+    warmup_iterations = max(1, min(100, iterations // 10))
+    for _ in range(warmup_iterations):
+        func()
+
+    # Collect garbage to ensure fair comparison
+    gc.collect()
+
+    # actual timing
+    with timer() as result:
+        for _ in range(iterations):
+            func()
+
+    return {
+        "total_time": result.elapsed_time,
+        "avg_time": result.elapsed_time / iterations,
+        "iterations": iterations,
+    }
+
+
+def main_run(func):
+    """
+    Run the benchmark function and print the results.
+
+    To use with iPython:
+    PYTHONPATH="." ipython perf/benchmarks/filename.py timeit
+
+    To use with asyncio:
+    PYTHONPATH="." ipython perf/benchmarks/filename.py
+    """
+    import asyncio
+    import sys
+
+    if len(sys.argv) > 1 and sys.argv[1] == "timeit":
+        from IPython import get_ipython
+
+        ipython = get_ipython()
+        if ipython:
+            ipython.run_line_magic("timeit", f"asyncio.run({func.__name__}(1))")
+        else:
+            print("ERROR: Use iPython to run the benchmark with timeit.")
+            sys.exit(1)
+    else:
+        asyncio.run(func())