refactor(loadgen): split internal package and simplify

- Split flat internal/ into internal/{matrix,spamoor,runner} packages
- Remove check subcommand (unused)
- Remove intermediate exported functions (ExecuteMatrix, ExecuteMatrixWithOverrides)
- Remove double validation in executeMatrix (already done by matrix.Load)
- Extract metric name and env var constants
- Store parsed timeout on Entry to avoid double time.ParseDuration
- Replace time.NewTimer per-iteration with single ticker in waitForSync
- Fix double time.Since call in poll loop
- Update README: fix burst-per-day default (0 not 2), remove stale
  serialization claim, document all subcommands clearly

Author: chatton

apps/loadgen/README.md

@@ -1,6 +1,6 @@
 # loadgen
 
-Standalone load generator for ev-node stress testing. Talks to a [spamoor-daemon](https://github.com/ethpandaops/spamoor) sidecar via HTTP API. Runs an in-process scheduler with configurable regular and burst workloads.
+Standalone load generator for ev-node stress testing. Talks to a [spamoor-daemon](https://github.com/ethpandaops/spamoor) sidecar via HTTP API.
 
 ## Architecture
 
@@ -14,32 +14,57 @@ ev-loadgen (this binary)  -->  spamoor-daemon  -->  ev-reth RPC
 - **spamoor-daemon** needs: a funded private key + ev-reth RPC URL
 - **ev-loadgen** needs: spamoor-daemon API URL + matrix JSON files
 
-## Commands
+## Modes
 
-```text
-ev-loadgen start                         # run continuous scheduler (regular + burst)
-ev-loadgen check                         # send 1 tx to verify spamoor → ev-reth connectivity
-ev-loadgen run <matrix.json>             # one-shot: run a custom matrix file
+### Daemon mode (`start`)
+
+Runs a continuous scheduler with regular and burst workloads. Designed for long-running deployments.
+
+```sh
+ev-loadgen start --spamoor-url=http://localhost:8080
 ```
 
-### start flags
+Regular workloads fire immediately at startup, then repeat at `--interval`. Per-run tx count = `tx-per-day / (24h / interval)`, overriding each matrix entry's `BENCH_COUNT_PER_SPAMMER`.
+
+Bursts are randomly spaced throughout a rolling 24h window. Set `--burst-per-day=0` (the default) to disable bursts entirely.
+
+#### start flags
 
 | Flag | Env | Default | Description |
 |------|-----|---------|-------------|
 | `--tx-per-day` | `BENCH_TX_PER_DAY` | `1000000` | sustained txs/day |
 | `--interval` | `BENCH_INTERVAL` | `1h` | regular workload frequency |
 | `--burst-tx-count` | `BENCH_BURST_TX_COUNT` | `500000` | txs per burst |
-| `--burst-per-day` | `BENCH_BURST_PER_DAY` | `2` | bursts per day, randomly spaced |
+| `--burst-per-day` | `BENCH_BURST_PER_DAY` | `0` | bursts per day, randomly spaced (0 = disabled) |
 | `--regular-matrix` | `BENCH_REGULAR_MATRIX` | `/home/ev/baseline.json` | path to regular matrix JSON |
 | `--burst-matrix` | `BENCH_BURST_MATRIX` | `/home/ev/burst.json` | path to burst matrix JSON |
 
-Global flag: `--spamoor-url` (or `BENCH_SPAMOOR_URL` env, default `http://spamoor-daemon:8080`)
+### CLI mode (one-shot commands)
+
+#### `run` — execute a matrix file
+
+Runs all entries from a matrix JSON file with probability filtering and sync waiting, then exits.
+
+```sh
+ev-loadgen run matrices/baseline.json --spamoor-url=http://localhost:8080
+```
 
-### Scheduling
+#### `burst` — trigger a single burst
 
-- **Regular**: fires immediately at startup, then repeats at `--interval`. Per-run tx count = `tx-per-day / (24h / interval)`. Overrides each matrix entry's `BENCH_COUNT_PER_SPAMMER`.
-- **Burst**: at startup + each midnight UTC, generates N random times across the day. Each burst overrides `BENCH_COUNT_PER_SPAMMER` = `burst-tx-count / NumSpammers`.
-- **Serialization**: a mutex prevents concurrent spamoor access. If burst fires during regular (or vice versa), it waits for the lock.
+Fires one burst workload immediately and exits.
+
+```sh
+ev-loadgen burst --spamoor-url=http://localhost:8080
+```
+
+| Flag | Env | Default | Description |
+|------|-----|---------|-------------|
+| `--tx-count` | `BENCH_BURST_TX_COUNT` | `500000` | total transactions for the burst |
+| `--burst-matrix` | `BENCH_BURST_MATRIX` | `/home/ev/burst.json` | path to burst matrix JSON |
+
+### Global flag
+
+`--spamoor-url` (or `BENCH_SPAMOOR_URL` env, default `http://spamoor-daemon:8080`)
 
 ## Quick Start
 
@@ -59,10 +84,13 @@ docker run -d --name spamoor -p 8080:8080 \
 # build
 cd apps/loadgen && go build -o ev-loadgen .
 
-# run with defaults (~1M tx/day, 2 bursts/day)
+# one-shot matrix run
+./ev-loadgen run matrices/baseline.json --spamoor-url=http://localhost:8080
+
+# continuous daemon (~1M tx/day, no bursts)
 ./ev-loadgen start --spamoor-url=http://localhost:8080
 
-# custom config
+# continuous daemon with bursts
 ./ev-loadgen start \
   --spamoor-url=http://localhost:8080 \
   --tx-per-day=500000 \
@@ -109,10 +137,10 @@ Each entry specifies a spamoor scenario, tx counts, and optional probability:
 | Field | Description |
 |---|---|
 | `scenario` | spamoor scenario name (`eoatx`, `gasburnertx`, `erc20tx`, `uniswap-swaps`, etc.) |
-| `probability` | 0.0–1.0, chance of running per invocation (omit = always run) |
+| `probability` | 0.0-1.0, chance of running per invocation (omit = always run) |
 | `timeout` | max duration per entry (default `15m`) |
 
-When using `start`, the `BENCH_COUNT_PER_SPAMMER` value in the matrix is overridden by the computed per-run count. The matrix value is still used by the `run` command.
+When using `start` or `burst`, `BENCH_COUNT_PER_SPAMMER` is overridden by the computed per-run count. The matrix value is used as-is by `run`.
 
 ## Build
 

apps/loadgen/cmd/burst.go

@@ -3,7 +3,8 @@ package cmd
 import (
 	"log"
 
-	"github.com/evstack/ev-node/apps/loadgen/internal"
+	"github.com/evstack/ev-node/apps/loadgen/internal/runner"
+	"github.com/evstack/ev-node/apps/loadgen/internal/spamoor"
 	"github.com/spf13/cobra"
 )
 
@@ -18,15 +19,14 @@ func newBurstCmd() *cobra.Command {
 		Short: "trigger a single burst workload immediately",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			spamoorAddr := resolveSpamoorURL()
-			api := internal.NewSpamoorClient(spamoorAddr)
+			api := spamoor.NewClient(resolveSpamoorURL())
 
-			if err := internal.WaitForSync(cmd.Context(), api); err != nil {
+			if err := runner.WaitForSync(cmd.Context(), api); err != nil {
 				return err
 			}
 
 			log.Printf("==> burst workload starting (%d tx)", txCount)
-			return internal.ExecuteMatrixWithOverridesFromFile(cmd.Context(), matrixPath, api, txCount)
+			return runner.ExecuteMatrixWithOverridesFromFile(cmd.Context(), matrixPath, api, txCount)
 		},
 	}
 

apps/loadgen/cmd/check.go

@@ -1,7 +1,7 @@
 package cmd
 
 import (
-	"github.com/evstack/ev-node/apps/loadgen/internal"
+	"github.com/evstack/ev-node/apps/loadgen/internal/spamoor"
 	"github.com/spf13/cobra"
 )
 
@@ -16,7 +16,7 @@ func NewRootCmd() *cobra.Command {
 
 	rootCmd.PersistentFlags().StringVar(&spamoorFlag, "spamoor-url", "", "spamoor-daemon API URL (env: BENCH_SPAMOOR_URL)")
 
-	rootCmd.AddCommand(newRunCmd(), newStartCmd(), newCheckCmd(), newBurstCmd())
+	rootCmd.AddCommand(newRunCmd(), newStartCmd(), newBurstCmd())
 
 	return rootCmd
 }
@@ -25,5 +25,5 @@ func resolveSpamoorURL() string {
 	if spamoorFlag != "" {
 		return spamoorFlag
 	}
-	return internal.SpamoorURL()
+	return spamoor.URL()
 }

apps/loadgen/cmd/root.go

@@ -1,7 +1,8 @@
 package cmd
 
 import (
-	"github.com/evstack/ev-node/apps/loadgen/internal"
+	"github.com/evstack/ev-node/apps/loadgen/internal/runner"
+	"github.com/evstack/ev-node/apps/loadgen/internal/spamoor"
 	"github.com/spf13/cobra"
 )
 
@@ -11,7 +12,7 @@ func newRunCmd() *cobra.Command {
 		Short: "run benchmarks from a matrix JSON file",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return internal.ExecuteMatrixFromFile(cmd.Context(), args[0], internal.NewSpamoorClient(resolveSpamoorURL()))
+			return runner.ExecuteMatrixFromFile(cmd.Context(), args[0], spamoor.NewClient(resolveSpamoorURL()))
 		},
 	}
 }

apps/loadgen/cmd/run.go

@@ -12,7 +12,8 @@ import (
 	"syscall"
 	"time"
 
-	"github.com/evstack/ev-node/apps/loadgen/internal"
+	"github.com/evstack/ev-node/apps/loadgen/internal/runner"
+	"github.com/evstack/ev-node/apps/loadgen/internal/spamoor"
 	"github.com/spf13/cobra"
 )
 
@@ -62,7 +63,7 @@ func runScheduler(parent context.Context, cfg startConfig) error {
 	defer cancel()
 
 	spamoorAddr := resolveSpamoorURL()
-	api := internal.NewSpamoorClient(spamoorAddr)
+	api := spamoor.NewClient(spamoorAddr)
 
 	runsPerDay := float64(24*time.Hour) / float64(cfg.interval)
 	regularTxPerRun := int(float64(cfg.txPerDay) / runsPerDay)
@@ -71,15 +72,15 @@ func runScheduler(parent context.Context, cfg startConfig) error {
 		cfg.txPerDay, cfg.interval, regularTxPerRun, cfg.burstTxCount, cfg.burstPerDay)
 	log.Printf("regular-matrix=%s burst-matrix=%s spamoor=%s", cfg.regularMatrix, cfg.burstMatrix, spamoorAddr)
 
-	if err := internal.WaitForSync(ctx, api); err != nil {
+	if err := runner.WaitForSync(ctx, api); err != nil {
 		return err
 	}
 
 	var wg sync.WaitGroup
 	runWorkload := func(label, matrixPath string, txCount int) {
 		defer wg.Done()
 		log.Printf("==> %s workload starting (%d tx)", label, txCount)
-		if err := internal.ExecuteMatrixWithOverridesFromFile(ctx, matrixPath, api, txCount); err != nil {
+		if err := runner.ExecuteMatrixWithOverridesFromFile(ctx, matrixPath, api, txCount); err != nil {
 			log.Printf("%s workload error: %v", label, err)
 		}
 	}
@@ -105,7 +106,7 @@ func runScheduler(parent context.Context, cfg startConfig) error {
 			burstTimer.Stop()
 			wg.Wait()
 			log.Printf("cleaning up spammers")
-			if err := internal.DeleteAllSpammers(api); err != nil {
+			if err := runner.DeleteAllSpammers(api); err != nil {
 				log.Printf("warning: shutdown cleanup failed: %v", err)
 			}
 			return nil
@@ -153,7 +154,6 @@ func nextBurstTimer(remaining int, window time.Duration) *time.Timer {
 	if remaining <= 0 {
 		t := time.NewTimer(0)
 		t.Stop()
-		// drain channel in case it fired before Stop
 		select {
 		case <-t.C:
 		default: