prescale 0.1.0__py3-none-any.whl

prescale-0.1.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: prescale
+Version: 0.1.0
+Summary: Launch-readiness load testing for developers - find what breaks before your users do
+Project-URL: Homepage, https://github.com/pyjeebz/prescale
+Project-URL: Documentation, https://github.com/pyjeebz/prescale#readme
+Project-URL: Repository, https://github.com/pyjeebz/prescale
+Author-email: Mujeeb Lawal-Saka <lawalsakamujeeb@gmail.com>
+License-Expression: Apache-2.0
+Keywords: cli,devtools,launch,load-testing,performance,stress-test
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Testing :: Traffic Generation
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: httpx[http2]>=0.24.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PreScale
+
+**Launch-readiness load testing for developers — find what breaks before your users do.**
+
+Point it at a URL. It ramps simulated traffic until something gives, then tells you, in plain English, what failed first and at what load.
+
+```bash
+pip install prescale
+prescale run https://staging.myapp.com
+```
+
+```
+Scale readiness: ⚠️  Survives ~90 concurrent users
+First failure   errors climb at ~150 users
+Likely cause    Server returned 5xx under load — likely DB pool exhaustion.
+```
+
+## Why
+
+- **Zero config** — no test scripts, no account, one command against a URL.
+- **Stack-agnostic** — Vercel, Fly, Railway, a VPS, serverless… it just needs a URL.
+- **An answer, not a histogram** — "you're good to ~90 users, your DB is the wall."
+- **Safe by default** — won't hammer a non-local host until you confirm you own it.
+
+## Usage
+
+```bash
+prescale run <url> [-u MAX_USERS] [-s STAGE_SECONDS] [--latency-wall S]
+                   [--error-threshold R] [-m METHOD] [--timeout S]
+                   [--i-own-this] [--json]
+```
+
+Requires Python 3.10+. Full docs and source: https://github.com/pyjeebz/PreScale
+
+## License
+
+Apache 2.0

prescale-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+prescale_cli/__init__.py,sha256=Qtat7bIe3CdaxOaJCtg8an3qjby75ADbT5EW-Sj5XAs,86
+prescale_cli/audit.py,sha256=4orY_sSSRW_S6KPOVKxHLECv6COiCQV1zQUFB-tQxfM,7785
+prescale_cli/loadtest.py,sha256=314Z9S6UOROScjJKYXLP3IwtALIwFvkgNYbUVrX4VYc,18723
+prescale_cli/main.py,sha256=kmaphvf__KyQcv4999lKLQv62WbDzcEb5LHpWCs-fPo,834
+prescale_cli/report.py,sha256=L9uSJztlyOMOD0JfnmUqSjDjvyFXgFgLnMi4BB-yE1U,13188
+prescale_cli/commands/__init__.py,sha256=eMuQR40Ye6ei4XbISb4dO1BwFk5RRqKIKGMxrztVu9Y,28
+prescale_cli/commands/audit.py,sha256=SlfvERJEh7hXYIGsO7B3AEQEaF9dWWcpMBIrqoifCic,2334
+prescale_cli/commands/run.py,sha256=1_PMnQt0KPFAONnh1e28KJGvRaPf0dTMhQhoS6-wlHY,12496
+prescale-0.1.0.dist-info/METADATA,sha256=znnbXTdKIdNoM7jVN_Zp131scX5QK3N0FyDcxDxdkqA,2520
+prescale-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+prescale-0.1.0.dist-info/entry_points.txt,sha256=zO_BktcyssCJPfVaT0Qc_qIifr1y00-I5I2N_xgP2rk,52
+prescale-0.1.0.dist-info/RECORD,,

prescale-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

prescale-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+prescale = prescale_cli.main:main

prescale_cli/__init__.py

@@ -0,0 +1,3 @@
+"""PreScale - launch-readiness load testing for developers."""
+
+__version__ = "0.1.0"

prescale_cli/audit.py

@@ -0,0 +1,206 @@
+"""Static scaling-hygiene audit for `prescale audit`.
+
+Fetches a page and a few of its static assets and flags the HTTP-level footguns
+that decide how a site handles traffic — compression, caching, CDN, HTTP
+version, cookies on assets — in about a second, without generating load.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from html.parser import HTMLParser
+from urllib.parse import urljoin, urlparse
+
+import httpx
+
+from prescale_cli import __version__
+
+_USER_AGENT = f"prescale/{__version__}"
+
+# Response/header markers that reveal a CDN or edge cache in front of the origin.
+_CDN_MARKERS = {
+    "cf-cache-status": "Cloudflare",
+    "x-vercel-cache": "Vercel",
+    "x-amz-cf-id": "CloudFront",
+    "x-served-by": "Fastly/Varnish",
+    "x-fastly-request-id": "Fastly",
+    "fly-request-id": "Fly",
+    "x-cache": "edge cache",
+}
+
+
+class AuditError(Exception):
+    """Raised when the target can't be reached at all."""
+
+
+@dataclass
+class Finding:
+    name: str
+    status: str  # "pass" | "warn" | "fail" | "info"
+    detail: str
+    fix: str | None = None
+
+
+class _AssetParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.urls: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs) -> None:
+        a = dict(attrs)
+        rel = a.get("rel", "").lower()
+        if tag == "link" and rel in ("stylesheet", "preload") and a.get("href"):
+            self.urls.append(a["href"])
+        elif tag == "script" and a.get("src"):
+            self.urls.append(a["src"])
+        elif tag == "img" and a.get("src"):
+            self.urls.append(a["src"])
+
+
+def extract_assets(html: str, base_url: str) -> list[str]:
+    """Same-origin static asset URLs referenced by the page, de-duplicated."""
+    parser = _AssetParser()
+    try:
+        parser.feed(html)
+    except Exception:
+        pass
+    base = urlparse(base_url)
+    origin = (base.scheme, base.netloc)
+    out: list[str] = []
+    seen: set[str] = set()
+    for raw in parser.urls:
+        full = urljoin(base_url, raw)
+        parsed = urlparse(full)
+        if parsed.scheme not in ("http", "https") or (parsed.scheme, parsed.netloc) != origin:
+            continue
+        if full not in seen:
+            seen.add(full)
+            out.append(full)
+    return out
+
+
+def _lower(headers) -> dict[str, str]:
+    return {k.lower(): v for k, v in headers.items()}
+
+
+def _compression_finding(content_encoding: str | None) -> Finding:
+    if content_encoding and any(
+        e in content_encoding.lower() for e in ("gzip", "br", "deflate", "zstd")
+    ):
+        return Finding("Compression", "pass", f"Responses are compressed ({content_encoding}).")
+    return Finding(
+        "Compression", "warn", "Responses aren't compressed.",
+        "Enable gzip or brotli at the server/CDN — smaller payloads, less bandwidth.",
+    )
+
+
+def _http_version_finding(version: str | None) -> Finding:
+    if version is None:
+        return Finding("HTTP version", "info", "Couldn't determine (install httpx[http2]).")
+    if version.lower().startswith(("http/2", "http/3", "h2", "h3")):
+        return Finding("HTTP version", "pass", f"Negotiated {version}.")
+    return Finding(
+        "HTTP version", "warn", f"Served over {version}.",
+        "Enable HTTP/2 — better multiplexing and fewer connection limits under load.",
+    )
+
+
+def _cdn_finding(headers_list: list[dict[str, str]]) -> Finding:
+    for headers in headers_list:
+        for marker, label in _CDN_MARKERS.items():
+            if marker in headers:
+                return Finding("CDN / edge cache", "pass",
+                               f"Detected ({label}: {headers[marker]}).")
+        if "cloudflare" in headers.get("server", "").lower():
+            return Finding("CDN / edge cache", "pass", "Detected (Cloudflare).")
+    return Finding(
+        "CDN / edge cache", "warn", "No CDN/edge-cache headers seen.",
+        "Put a CDN in front so the origin doesn't serve every request.",
+    )
+
+
+def _asset_caching_finding(assets: list[tuple[str, dict[str, str]]]) -> Finding:
+    if not assets:
+        return Finding("Static asset caching", "info", "No static assets found to check.")
+    uncached = []
+    for url, headers in assets:
+        cc = headers.get("cache-control", "").lower()
+        cacheable = ("immutable" in cc) or (
+            "max-age" in cc and not any(x in cc for x in ("no-store", "no-cache", "max-age=0"))
+        )
+        validator = "etag" in headers or "last-modified" in headers
+        if not (cacheable or validator):
+            uncached.append(url)
+    if not uncached:
+        return Finding("Static asset caching", "pass",
+                       f"All {len(assets)} sampled assets are cacheable.")
+    status = "fail" if len(uncached) == len(assets) else "warn"
+    return Finding(
+        "Static asset caching", status,
+        f"{len(uncached)} of {len(assets)} sampled assets have no caching headers.",
+        "Set Cache-Control: max-age (or an ETag) so clients and CDNs don't re-fetch them.",
+    )
+
+
+def _asset_cookie_finding(assets: list[tuple[str, dict[str, str]]]) -> Finding:
+    if not assets:
+        return Finding("Cookies on assets", "info", "No static assets found to check.")
+    cookied = [url for url, headers in assets if "set-cookie" in headers]
+    if not cookied:
+        return Finding("Cookies on assets", "pass", "No cookies set on sampled static assets.")
+    return Finding(
+        "Cookies on assets", "warn", f"{len(cookied)} asset(s) set cookies.",
+        "Don't set cookies on static assets — it defeats CDN and proxy caching.",
+    )
+
+
+def _baseline_finding(size_bytes: int, seconds: float) -> Finding:
+    kb = size_bytes / 1024
+    detail = f"HTML {kb:.0f} KB, responded in {seconds * 1000:.0f} ms."
+    if kb > 1024:
+        return Finding("Baseline", "warn", detail,
+                       "Large HTML payload — trim, split, or stream it.")
+    if seconds > 1.0:
+        return Finding("Baseline", "warn", detail,
+                       "Slow baseline response — investigate work on the main route.")
+    return Finding("Baseline", "info", detail)
+
+
+async def run_audit(url: str, *, timeout: float = 10.0, max_assets: int = 6) -> list[Finding]:
+    """Fetch the page and a sample of its assets; return scaling-hygiene findings."""
+    headers = {"User-Agent": _USER_AGENT, "Accept-Encoding": "gzip, deflate, br"}
+    try:
+        client = httpx.AsyncClient(http2=True, timeout=timeout,
+                                   follow_redirects=True, headers=headers)
+        http2_capable = True
+    except ImportError:  # h2 not installed
+        client = httpx.AsyncClient(timeout=timeout, follow_redirects=True, headers=headers)
+        http2_capable = False
+
+    async with client:
+        start = time.perf_counter()
+        try:
+            resp = await client.get(url)
+        except httpx.HTTPError as exc:
+            raise AuditError(f"Couldn't reach {url}: {exc}") from exc
+        elapsed = time.perf_counter() - start
+        page_headers = _lower(resp.headers)
+
+        asset_results: list[tuple[str, dict[str, str]]] = []
+        for asset in extract_assets(resp.text, url)[:max_assets]:
+            try:
+                ar = await client.get(asset)
+            except httpx.HTTPError:
+                continue
+            asset_results.append((asset, _lower(ar.headers)))
+
+    all_headers = [page_headers] + [h for _, h in asset_results]
+    return [
+        _compression_finding(page_headers.get("content-encoding")),
+        _http_version_finding(resp.http_version if http2_capable else None),
+        _cdn_finding(all_headers),
+        _asset_caching_finding(asset_results),
+        _asset_cookie_finding(asset_results),
+        _baseline_finding(len(resp.content), elapsed),
+    ]

prescale_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands package."""

prescale_cli/commands/audit.py

@@ -0,0 +1,75 @@
+"""`prescale audit` - fast static scaling-hygiene check for a URL (no load)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from urllib.parse import urlparse
+
+import click
+from rich.console import Console
+
+from prescale_cli.audit import AuditError, Finding, run_audit
+
+console = Console()
+
+_ICONS = {
+    "pass": "[green]✓[/green]",
+    "warn": "[yellow]⚠[/yellow]",
+    "fail": "[red]✗[/red]",
+    "info": "[dim]•[/dim]",
+}
+
+
+@click.command()
+@click.argument("url")
+@click.option("--timeout", default=10.0, type=float, help="Per-request timeout in seconds.")
+@click.option("--json", "as_json", is_flag=True, help="Emit findings as JSON.")
+def audit(url: str, timeout: float, as_json: bool) -> None:
+    """Static scaling-hygiene check for URL (no load).
+
+    \b
+    Examples:
+        prescale audit https://myapp.com
+        prescale audit https://myapp.com --json
+    """
+    parsed = urlparse(url)
+    if not parsed.scheme or not parsed.netloc:
+        console.print(f"[red]Error:[/red] '{url}' doesn't look like a URL "
+                      "(expected e.g. https://myapp.com).")
+        raise SystemExit(1)
+
+    try:
+        if as_json:
+            findings = asyncio.run(run_audit(url, timeout=timeout))
+        else:
+            with console.status("[bold blue]Auditing…"):
+                findings = asyncio.run(run_audit(url, timeout=timeout))
+    except AuditError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise SystemExit(1)
+
+    if as_json:
+        console.print(json.dumps(
+            [{"name": f.name, "status": f.status, "detail": f.detail, "fix": f.fix}
+             for f in findings],
+            indent=2,
+        ))
+        return
+
+    _render(url, findings)
+
+
+def _render(url: str, findings: list[Finding]) -> None:
+    console.print(f"\n[bold]PreScale audit[/bold] — [cyan]{url}[/cyan]\n")
+    for f in findings:
+        console.print(f"{_ICONS.get(f.status, '•')} [bold]{f.name}[/bold]  {f.detail}")
+        if f.fix:
+            console.print(f"    [dim]{f.fix}[/dim]")
+
+    counts = {s: sum(1 for f in findings if f.status == s) for s in ("pass", "warn", "fail")}
+    console.print(
+        f"\n[green]{counts['pass']} passed[/green] · "
+        f"[yellow]{counts['warn']} warnings[/yellow] · "
+        f"[red]{counts['fail']} failed[/red]"
+    )