springdocker 1.0.1__py3-none-any.whl

springdocker/benchmarks/runner.py

@@ -0,0 +1,343 @@
+from __future__ import annotations
+
+import argparse
+import csv
+import socket
+import subprocess
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from pathlib import Path
+
+from springdocker.benchmarks.generate import EXPECTED_CSV_HEADER, default_scenarios
+
+
+@dataclass(frozen=True)
+class RunnerOptions:
+    profile: str
+    runs_override: int | None
+    skip_native: bool
+    native_duration: str | None
+    native_vus: int | None
+    native_cpu_work: int | None
+    java_version: int
+    regenerate_scenarios: bool
+
+
+def parse_runner_args(profile: str, extra_args: list[str]) -> RunnerOptions:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--runs", type=int, default=None)
+    parser.add_argument("--skip-native", action="store_true")
+    parser.add_argument("--native-duration", default=None)
+    parser.add_argument("--native-vus", type=int, default=None)
+    parser.add_argument("--native-cpu-work", type=int, default=None)
+    parser.add_argument("--java-version", type=int, default=25)
+    parser.add_argument(
+        "--regenerate-scenarios",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+    )
+    parsed, unknown = parser.parse_known_args(extra_args)
+    if unknown:
+        raise ValueError(f"unknown runner arguments: {' '.join(unknown)}")
+    return RunnerOptions(
+        profile=profile,
+        runs_override=parsed.runs,
+        skip_native=parsed.skip_native,
+        native_duration=parsed.native_duration,
+        native_vus=parsed.native_vus,
+        native_cpu_work=parsed.native_cpu_work,
+        java_version=parsed.java_version,
+        regenerate_scenarios=parsed.regenerate_scenarios,
+    )
+
+
+def _docker_version() -> str:
+    try:
+        out = subprocess.run(
+            ["docker", "--version"],
+            check=False,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+        if out:
+            return out.replace(",", "").split()[-1]
+    except OSError:
+        pass
+    return "unknown"
+
+
+def _wait_readiness(base_url: str, timeout_seconds: float = 40.0) -> int:
+    start = time.time()
+    while time.time() - start < timeout_seconds:
+        probe = subprocess.run(
+            ["curl", "-fsS", base_url],
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        if probe.returncode == 0:
+            return int((time.time() - start) * 1000)
+        time.sleep(0.25)
+    return -1
+
+
+def _append_row(path: Path, row: list[str]) -> None:
+    with path.open("a", newline="", encoding="utf-8") as handle:
+        writer = csv.writer(handle)
+        writer.writerow(row)
+
+
+def _ensure_csv(path: Path) -> None:
+    if path.exists():
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(EXPECTED_CSV_HEADER, encoding="utf-8")
+
+
+def _tag_for(scenario_id: str, variant_name: str) -> str:
+    return f"bench-{scenario_id}:{variant_name}".replace("_", "-")
+
+
+def _runtime_flags(cpuset_cpus: str | None, memory_limit: str | None, normalized_runtime: bool) -> list[str]:
+    flags: list[str] = []
+    if cpuset_cpus:
+        flags.extend(["--cpuset-cpus", cpuset_cpus])
+    if memory_limit:
+        flags.extend(["--memory", memory_limit])
+    if normalized_runtime:
+        flags.extend(["--read-only", "--cap-drop=ALL", "--security-opt=no-new-privileges", "--tmpfs", "/tmp"])
+    return flags
+
+
+def _default_runs_for(profile: str, scenario_id: str) -> int:
+    if scenario_id == "04-jep483-aot-cache":
+        return 8 if profile == "quick" else 15
+    return 3 if profile == "quick" else 10
+
+
+def _run_standard_scenario(
+    project_root: Path,
+    scenario_dir: Path,
+    runs: int,
+    run_profile: str,
+    cpuset_cpus: str | None,
+    memory_limit: str | None,
+    warmup_runs: int,
+    port_seed: int,
+    normalized_runtime: bool,
+) -> None:
+    raw_csv = scenario_dir / "results" / "raw.csv"
+    _ensure_csv(raw_csv)
+    host = socket.gethostname()
+    docker_version = _docker_version()
+    scenario = scenario_dir.name
+    print(f"\n=== Scenario: {scenario} (runs={runs}, profile={run_profile}) ===")
+
+    for index, variant_dir in enumerate(sorted((scenario_dir / "variants").glob("*"))):
+        if not variant_dir.is_dir():
+            continue
+        dockerfile = variant_dir / "Dockerfile"
+        if not dockerfile.exists():
+            continue
+        variant = variant_dir.name
+        image_tag = _tag_for(scenario, variant)
+        host_port = str(19081 + (port_seed * 50) + index)
+        runtime_flags = _runtime_flags(cpuset_cpus=cpuset_cpus, memory_limit=memory_limit, normalized_runtime=normalized_runtime)
+        print(f"-- variant: {variant}")
+
+        for warmup_number in range(1, warmup_runs + 1):
+            warmup_container = f"{image_tag.replace(':', '-')}-warmup-{warmup_number}"
+            subprocess.run(
+                [
+                    "docker",
+                    "run",
+                    "-d",
+                    "--rm",
+                    "--name",
+                    warmup_container,
+                    "-p",
+                    f"{host_port}:8081",
+                    *runtime_flags,
+                    image_tag,
+                ],
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            warmup_start = _wait_readiness("http://localhost:" + host_port + "/actuator/health/readiness")
+            subprocess.run(
+                ["docker", "stop", warmup_container],
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            print(f"warmup {warmup_number}: startup={warmup_start}")
+
+        for run_number in range(1, runs + 1):
+            build_start = time.time()
+            build = subprocess.run(
+                ["docker", "build", "-q", "-f", str(dockerfile), "-t", image_tag, "."],
+                cwd=project_root,
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            build_ms = int((time.time() - build_start) * 1000)
+            if build.returncode != 0:
+                _append_row(
+                    raw_csv,
+                    [
+                        time.strftime("%Y-%m-%d"),
+                        scenario,
+                        variant,
+                        str(run_number),
+                        "-1",
+                        "-1",
+                        "-1",
+                        "build_failed",
+                        "docker build failed",
+                        host,
+                        docker_version,
+                        run_profile,
+                        "",
+                        "",
+                        "",
+                        "",
+                        "",
+                    ],
+                )
+                print(f"run {run_number}: build failed")
+                continue
+
+            image_size = subprocess.run(
+                ["docker", "image", "inspect", image_tag, "--format", "{{.Size}}"],
+                check=False,
+                capture_output=True,
+                text=True,
+            ).stdout.strip() or "-1"
+
+            container_name = f"{image_tag.replace(':', '-')}-{run_number}"
+            subprocess.run(
+                [
+                    "docker",
+                    "run",
+                    "-d",
+                    "--rm",
+                    "--name",
+                    container_name,
+                    "-p",
+                    f"{host_port}:8081",
+                    *runtime_flags,
+                    image_tag,
+                ],
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            startup_ms = _wait_readiness("http://localhost:" + host_port + "/actuator/health/readiness")
+            status = "ok" if startup_ms >= 0 else "readiness_failed"
+            notes = "" if status == "ok" else "readiness endpoint not reachable"
+            subprocess.run(["docker", "stop", container_name], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+            _append_row(
+                raw_csv,
+                [
+                    time.strftime("%Y-%m-%d"),
+                    scenario,
+                    variant,
+                    str(run_number),
+                    str(build_ms),
+                    image_size,
+                    str(startup_ms),
+                    status,
+                    notes,
+                    host,
+                    docker_version,
+                    run_profile,
+                    "",
+                    "",
+                    "",
+                    "",
+                    "",
+                ],
+            )
+            print(
+                f"run {run_number}: build={build_ms}ms size={image_size} "
+                f"startup={startup_ms} status={status}"
+            )
+
+
+def run_benchmarks(
+    project_root: Path,
+    build_tool: str,
+    profile: str,
+    extra_args: list[str],
+    cpuset_cpus: str | None = None,
+    memory_limit: str | None = None,
+    warmup_runs: int = 0,
+    max_workers: int = 1,
+    normalized_runtime: bool = False,
+) -> int:
+    options = parse_runner_args(profile=profile, extra_args=extra_args)
+    print(f"Using profile: {options.profile}")
+    print(f"Project root: {project_root}")
+    print(f"Build tool: {build_tool}")
+    scenarios = default_scenarios(build_tool=build_tool, java_version=options.java_version)
+    print(f"Scenarios loaded: {len(scenarios)}")
+
+    work_items: list[tuple[int, Path, int]] = []
+    for scenario_index, scenario in enumerate(scenarios):
+        if scenario.scenario_type == "native":
+            if options.skip_native:
+                print(f"Skipping native scenario: {scenario.id}")
+                continue
+            print(f"Skipping native scenario in internal runner: {scenario.id}")
+            continue
+        scenario_dir = project_root / "benchmarks" / scenario.id
+        if not (scenario_dir / "variants").exists():
+            print(f"Skipping missing scenario directory: {scenario.id}")
+            continue
+        runs = options.runs_override or _default_runs_for(profile=options.profile, scenario_id=scenario.id)
+        work_items.append((scenario_index, scenario_dir, runs))
+
+    if max_workers <= 1 or len(work_items) <= 1:
+        for scenario_index, scenario_dir, runs in work_items:
+            _run_standard_scenario(
+                project_root=project_root,
+                scenario_dir=scenario_dir,
+                runs=runs,
+                run_profile=options.profile,
+                cpuset_cpus=cpuset_cpus,
+                memory_limit=memory_limit,
+                warmup_runs=warmup_runs,
+                port_seed=scenario_index,
+                normalized_runtime=normalized_runtime,
+            )
+    else:
+        print(f"Running standard scenarios concurrently (max_workers={max_workers})")
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = {
+                executor.submit(
+                    _run_standard_scenario,
+                    project_root=project_root,
+                    scenario_dir=scenario_dir,
+                    runs=runs,
+                    run_profile=options.profile,
+                    cpuset_cpus=cpuset_cpus,
+                    memory_limit=memory_limit,
+                    warmup_runs=warmup_runs,
+                    port_seed=scenario_index,
+                    normalized_runtime=normalized_runtime,
+                ): scenario_dir.name
+                for scenario_index, scenario_dir, runs in work_items
+            }
+            for future in as_completed(futures):
+                scenario_name = futures[future]
+                try:
+                    future.result()
+                except Exception as exc:  # pragma: no cover - exercised via command-level integration flow
+                    print(f"Scenario failed: {scenario_name}: {exc}")
+                    return 1
+    print("\nAll done. CSV results were updated.")
+    return 0

springdocker/cli.py

@@ -0,0 +1,289 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .commands import (
+    cmd_benchmark_analyze,
+    cmd_benchmark_compare,
+    cmd_benchmark_generate,
+    cmd_benchmark_run,
+    cmd_dockerfile_generate,
+    cmd_doctor,
+    cmd_explain,
+    cmd_init,
+    cmd_inspect,
+)
+from .config import (
+    load_config,
+    resolve_benchmark_generate_config,
+    resolve_benchmark_run_config,
+    resolve_dockerfile_generate_config,
+    resolve_doctor_config,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="springdocker",
+        description="CLI for Dockerfile and benchmark workflows in Spring Boot Maven/Gradle projects.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def add_common_options(p: argparse.ArgumentParser, with_build_tool: bool = True) -> None:
+        p.add_argument("--project-root", default=".", help="Project root path (default: current directory)")
+        if with_build_tool:
+            p.add_argument("--build-tool", choices=["maven", "gradle"], default=None,
+                           help="Override auto-detected build tool")
+
+    init = sub.add_parser("init", help="Generate starter .springdocker.toml for this project")
+    add_common_options(init)
+    init.add_argument("--config", default=".springdocker.toml", help="Config file path to create")
+    init.add_argument(
+        "--profile",
+        choices=["quick", "full"],
+        default="quick",
+        help="Default benchmark run profile to write in the generated config",
+    )
+    init.add_argument("--print", action="store_true", dest="print_only", help="Print config template to stdout")
+    init.add_argument("--force", action="store_true", help="Overwrite existing config file")
+
+    doctor = sub.add_parser("doctor", help="Detect project and validate basic prerequisites")
+    add_common_options(doctor)
+
+    inspect = sub.add_parser("inspect", help="Inspect project metadata and static compatibility signals")
+    add_common_options(inspect)
+    inspect.add_argument("--format", choices=["table", "json"], default="table")
+
+    explain = sub.add_parser("explain", help="Explain a springdocker-generated Dockerfile")
+    add_common_options(explain)
+    explain.add_argument("dockerfile", nargs="?", default="Dockerfile.generated")
+    explain.add_argument("--format", choices=["table", "json"], default="table")
+
+    dockerfile = sub.add_parser("dockerfile", help="Dockerfile operations")
+    dockerfile_sub = dockerfile.add_subparsers(dest="dockerfile_command", required=True)
+    gen = dockerfile_sub.add_parser("generate", help="Generate Dockerfile via existing wizard")
+    add_common_options(gen)
+    gen.add_argument("--output", default=None, help="Output Dockerfile path")
+    gen.add_argument("--java-version", type=int, default=None, help="Java major version for generated Dockerfile")
+    gen.add_argument(
+        "--wizard-arg",
+        action="append",
+        default=None,
+        help="Extra argument forwarded to tools/dockerfile_wizard.py; repeat for multiple args",
+    )
+    gen.add_argument(
+        "--use-legacy-scripts",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Use project scripts instead of internal implementation (or set SPRINGDOCKER_LEGACY_SCRIPTS=1)",
+    )
+
+    bench = sub.add_parser("benchmark", help="Benchmark operations")
+    bench_sub = bench.add_subparsers(dest="benchmark_command", required=True)
+
+    bench_gen = bench_sub.add_parser("generate", help="Generate benchmark variants for selected build tool")
+    add_common_options(bench_gen)
+    bench_gen.add_argument("--java-version", type=int, default=None)
+    bench_gen.add_argument(
+        "--use-legacy-scripts",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Use project scripts instead of internal implementation (or set SPRINGDOCKER_LEGACY_SCRIPTS=1)",
+    )
+
+    bench_run = bench_sub.add_parser("run", help="Run benchmark orchestration")
+    add_common_options(bench_run)
+    bench_run.add_argument("--profile", choices=["quick", "full"], default=None)
+    bench_run.add_argument(
+        "--config",
+        default=".springdocker.toml",
+        help="Path to TOML config file relative to project root (default: .springdocker.toml)",
+    )
+    bench_run.add_argument(
+        "--runner-arg",
+        action="append",
+        default=None,
+        help="Extra argument forwarded to benchmarks/common/run_all_benchmarks.py; repeat for multiple args",
+    )
+    bench_run.add_argument("--cpuset-cpus", default=None, help="Pin benchmark containers to a CPU set")
+    bench_run.add_argument("--memory", default=None, help="Limit benchmark containers to a memory amount")
+    bench_run.add_argument(
+        "--warmup-runs",
+        type=int,
+        default=None,
+        help="Run extra warmup iterations before recording benchmark rows",
+    )
+    bench_run.add_argument(
+        "--max-workers",
+        type=int,
+        default=None,
+        help="Run standard benchmark scenarios concurrently with up to this many workers",
+    )
+    bench_run.add_argument(
+        "--normalized-runtime",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Apply normalized container runtime flags for reproducible benchmark runs",
+    )
+    bench_run.add_argument(
+        "--use-legacy-scripts",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Use project scripts instead of internal implementation (or set SPRINGDOCKER_LEGACY_SCRIPTS=1)",
+    )
+
+    bench_analyze = bench_sub.add_parser("analyze", help="Analyze benchmark CSV")
+    add_common_options(bench_analyze, with_build_tool=False)
+    bench_analyze.add_argument("raw_csv", help="Path to results raw.csv")
+    bench_analyze.add_argument("--format", choices=["table", "json"], default="table")
+    bench_analyze.add_argument("--scenario", default=None, help="Filter by scenario id")
+    bench_analyze.add_argument("--variant", default=None, help="Filter by variant name")
+    bench_analyze.add_argument("--output", default=None, help="Write output to file instead of stdout")
+    bench_analyze.add_argument(
+        "--fail-on-success-rate-below",
+        type=float,
+        default=None,
+        help="Exit non-zero when any variant success rate is below this percentage (0-100)",
+    )
+    bench_analyze.add_argument("--baseline", default=None, help="Path to a baseline JSON report")
+    bench_analyze.add_argument(
+        "--fail-on-regression-above",
+        type=float,
+        default=None,
+        help="Exit non-zero when any tracked metric regresses above this percentage",
+    )
+
+    bench_compare = bench_sub.add_parser("compare", help="Compare benchmark variants against a baseline")
+    add_common_options(bench_compare, with_build_tool=False)
+    bench_compare.add_argument("raw_csv", help="Path to results raw.csv")
+    bench_compare.add_argument("--baseline-variant", required=True, help="Variant name to use as the baseline")
+    bench_compare.add_argument("--scenario", default=None, help="Filter by scenario id")
+    bench_compare.add_argument("--format", choices=["table", "json"], default="table")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    project_root = Path(args.project_root).resolve()
+
+    if args.command == "init":
+        config_path = Path(args.config)
+        if not config_path.is_absolute():
+            config_path = project_root / config_path
+        return cmd_init(
+            project_root=project_root,
+            build_tool=args.build_tool,
+            config_path=config_path,
+            profile=args.profile,
+            force=args.force,
+            print_only=args.print_only,
+        )
+
+    if args.command == "doctor":
+        config_path = project_root / ".springdocker.toml"
+        loaded = load_config(config_path)
+        resolved_doctor = resolve_doctor_config(cli_build_tool=args.build_tool, loaded_config=loaded)
+        return cmd_doctor(project_root, resolved_doctor.build_tool)
+
+    if args.command == "inspect":
+        return cmd_inspect(project_root=project_root, build_tool=args.build_tool, output_format=args.format)
+
+    if args.command == "explain":
+        return cmd_explain(project_root=project_root, dockerfile_path=args.dockerfile, output_format=args.format)
+
+    if args.command == "dockerfile" and args.dockerfile_command == "generate":
+        loaded = load_config(project_root / ".springdocker.toml")
+        resolved_dockerfile = resolve_dockerfile_generate_config(
+            cli_build_tool=args.build_tool,
+            cli_output=args.output,
+            cli_java_version=args.java_version,
+            cli_wizard_args=args.wizard_arg,
+            cli_use_legacy_scripts=args.use_legacy_scripts,
+            loaded_config=loaded,
+        )
+        return cmd_dockerfile_generate(
+            project_root=project_root,
+            build_tool=resolved_dockerfile.build_tool,
+            output=resolved_dockerfile.output,
+            java_version=resolved_dockerfile.java_version,
+            must_have_modules_file=resolved_dockerfile.must_have_modules_file,
+            extra_args=resolved_dockerfile.wizard_args,
+            use_legacy_scripts=resolved_dockerfile.use_legacy_scripts,
+        )
+
+    if args.command == "benchmark" and args.benchmark_command == "generate":
+        loaded = load_config(project_root / ".springdocker.toml")
+        resolved_generate = resolve_benchmark_generate_config(
+            cli_build_tool=args.build_tool,
+            cli_java_version=args.java_version,
+            cli_use_legacy_scripts=args.use_legacy_scripts,
+            loaded_config=loaded,
+        )
+        return cmd_benchmark_generate(
+            project_root=project_root,
+            build_tool=resolved_generate.build_tool,
+            java_version=resolved_generate.java_version,
+            use_legacy_scripts=resolved_generate.use_legacy_scripts,
+        )
+
+    if args.command == "benchmark" and args.benchmark_command == "run":
+        config_path = Path(args.config)
+        if not config_path.is_absolute():
+            config_path = project_root / config_path
+        loaded = load_config(config_path)
+        resolved_run = resolve_benchmark_run_config(
+            cli_build_tool=args.build_tool,
+            cli_profile=args.profile,
+            cli_runner_args=args.runner_arg,
+            cli_cpuset_cpus=args.cpuset_cpus,
+            cli_memory_limit=args.memory,
+            cli_warmup_runs=args.warmup_runs,
+            cli_max_workers=args.max_workers,
+            cli_normalized_runtime=args.normalized_runtime,
+            cli_use_legacy_scripts=args.use_legacy_scripts,
+            loaded_config=loaded,
+        )
+        return cmd_benchmark_run(
+            project_root=project_root,
+            build_tool=resolved_run.build_tool,
+            profile=resolved_run.profile,
+            extra_args=resolved_run.runner_args,
+            cpuset_cpus=resolved_run.cpuset_cpus,
+            memory_limit=resolved_run.memory_limit,
+            warmup_runs=resolved_run.warmup_runs,
+            max_workers=resolved_run.max_workers,
+            normalized_runtime=resolved_run.normalized_runtime,
+            use_legacy_scripts=resolved_run.use_legacy_scripts,
+        )
+
+    if args.command == "benchmark" and args.benchmark_command == "analyze":
+        return cmd_benchmark_analyze(
+            project_root=project_root,
+            raw_csv=args.raw_csv,
+            output_format=args.format,
+            scenario=args.scenario,
+            variant=args.variant,
+            output_path=args.output,
+            fail_on_success_rate_below=args.fail_on_success_rate_below,
+            baseline_path=args.baseline,
+            fail_on_regression_above=args.fail_on_regression_above,
+        )
+
+    if args.command == "benchmark" and args.benchmark_command == "compare":
+        return cmd_benchmark_compare(
+            project_root=project_root,
+            raw_csv=args.raw_csv,
+            baseline_variant=args.baseline_variant,
+            output_format=args.format,
+            scenario=args.scenario,
+        )
+
+    parser.error("unknown command")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())