feat: add archive test source for ZIP and tar.gz files (#179)

## Summary

- Add new `archive` source type under `tests.source` that downloads and
extracts ZIP or tar.gz archives from URLs or local paths, then discovers
tests via glob patterns within extracted contents
- Automatically detect and convert GitHub Actions artifact browser URLs
to API calls with bearer token auth
- Support parallel range-request downloads (8 workers, 25 MiB chunks)
with automatic fallback to sequential when the server doesn't support
range requests
- Cache downloaded archives locally so repeated runs with the same URL
skip the download
- Auto-extract inner tarballs found inside ZIP files (e.g. GitHub
Actions artifacts)
- Pass `BENCHMARKOOR_RUNNER_GITHUB_TOKEN` into the Docker container in
the GitHub Action
- Fix null `tests` array crash in UI suite cell tooltip

## Example config

```yaml
tests:
  source:
    archive:
      file: https://github.com/NethermindEth/gas-benchmarks/actions/runs/123/artifacts/456
      pre_run_steps:
        - "perf-devnet-3/gas-bump.txt"
      steps:
        setup:
          - "perf-devnet-3/tests/setup/*.txt"
        test:
          - "perf-devnet-3/tests/test/*.txt"
        cleanup:
          - "perf-devnet-3/tests/cleanup/*.txt"
```

## Test plan

- [x] Config validation tests (valid archive, missing file, multiple
sources)
- [x] `IsConfigured()` test for archive source
- [x] Local ZIP and tar.gz extraction tests
- [x] Inner tarball auto-extraction test
- [x] GitHub artifact URL detection and conversion test
- [x] Download caching test (second run skips download)
- [x] Parallel range-request download test with httptest server
- [x] Sequential fallback test
- [x] Bearer token forwarding test
- [x] Format detection by extension and magic bytes
- [x] Race detector clean on parallel download

Author: skylenet

action.yaml

@@ -203,6 +203,7 @@ runs:
         DOCKER_CMD="$DOCKER_CMD -v /proc/sys/vm/drop_caches:/host_drop_caches"
         DOCKER_CMD="$DOCKER_CMD -v /sys/devices/system/cpu:/host_sys_cpu"
         DOCKER_CMD="$DOCKER_CMD -v /sys/fs/cgroup:/sys/fs/cgroup:ro"
+        DOCKER_CMD="$DOCKER_CMD -e BENCHMARKOOR_RUNNER_GITHUB_TOKEN=${{ inputs.github-token }}"
         DOCKER_CMD="$DOCKER_CMD -e BENCHMARKOOR_RUNNER_DROP_CACHES_PATH=/host_drop_caches"
         DOCKER_CMD="$DOCKER_CMD -e BENCHMARKOOR_RUNNER_CPU_SYSFS_PATH=/host_sys_cpu"
         DOCKER_CMD="$DOCKER_CMD -e BENCHMARKOOR_RUNNER_BENCHMARK_RESULTS_DIR=/app/results"

pkg/config/config.go

@@ -148,9 +148,10 @@ type TestsConfig struct {
 // SourceConfig defines where to find test files.
 type SourceConfig struct {
 	// New unified source options.
-	Git          *GitSourceV2        `yaml:"git,omitempty" mapstructure:"git"`
-	Local        *LocalSourceV2      `yaml:"local,omitempty" mapstructure:"local"`
-	EESTFixtures *EESTFixturesSource `yaml:"eest_fixtures,omitempty" mapstructure:"eest_fixtures"`
+	Git          *GitSourceV2         `yaml:"git,omitempty" mapstructure:"git"`
+	Local        *LocalSourceV2       `yaml:"local,omitempty" mapstructure:"local"`
+	Archive      *ArchiveSourceConfig `yaml:"archive,omitempty" mapstructure:"archive"`
+	EESTFixtures *EESTFixturesSource  `yaml:"eest_fixtures,omitempty" mapstructure:"eest_fixtures"`
 }
 
 // EESTFixturesSource defines an EEST fixtures source from GitHub releases, artifacts,
@@ -330,6 +331,14 @@ type LocalSourceV2 struct {
 	Steps       *StepsConfig `yaml:"steps,omitempty" mapstructure:"steps"`
 }
 
+// ArchiveSourceConfig defines an archive file source for tests.
+// The file can be a local path or a URL (HTTP/HTTPS) to a ZIP or tar.gz archive.
+type ArchiveSourceConfig struct {
+	File        string       `yaml:"file" mapstructure:"file"`
+	PreRunSteps []string     `yaml:"pre_run_steps,omitempty" mapstructure:"pre_run_steps"`
+	Steps       *StepsConfig `yaml:"steps,omitempty" mapstructure:"steps"`
+}
+
 // StepsConfig defines glob patterns for each step type.
 type StepsConfig struct {
 	Setup   []string `yaml:"setup,omitempty" mapstructure:"setup"`
@@ -339,7 +348,7 @@ type StepsConfig struct {
 
 // IsConfigured returns true if any test source is configured.
 func (s *SourceConfig) IsConfigured() bool {
-	return s.Git != nil || s.Local != nil || s.EESTFixtures != nil
+	return s.Git != nil || s.Local != nil || s.Archive != nil || s.EESTFixtures != nil
 }
 
 // DefaultContainerDir is the default container mount path for data directories.
@@ -1096,12 +1105,16 @@ func (s *SourceConfig) Validate() error {
 		count++
 	}
 
+	if s.Archive != nil {
+		count++
+	}
+
 	if s.EESTFixtures != nil {
 		count++
 	}
 
 	if count > 1 {
-		return fmt.Errorf("cannot specify multiple sources (git, local, eest_fixtures)")
+		return fmt.Errorf("cannot specify multiple sources (git, local, archive, eest_fixtures)")
 	}
 
 	if s.Git != nil {
@@ -1124,6 +1137,12 @@ func (s *SourceConfig) Validate() error {
 		}
 	}
 
+	if s.Archive != nil {
+		if s.Archive.File == "" {
+			return fmt.Errorf("archive.file is required")
+		}
+	}
+
 	if s.EESTFixtures != nil {
 		if err := s.EESTFixtures.validate(); err != nil {
 			return err

pkg/config/config_test.go

@@ -609,6 +609,46 @@ func TestSourceConfig_Validate(t *testing.T) {
 			wantErr:   true,
 			errSubstr: "does not exist",
 		},
+		{
+			name: "valid archive source with URL",
+			source: SourceConfig{
+				Archive: &ArchiveSourceConfig{
+					File: "https://example.com/fixtures.zip",
+				},
+			},
+			wantErr: false,
+		},
+		{
+			name: "valid archive source with local file",
+			source: SourceConfig{
+				Archive: &ArchiveSourceConfig{
+					File: fixturesTarball,
+				},
+			},
+			wantErr: false,
+		},
+		{
+			name: "archive missing file",
+			source: SourceConfig{
+				Archive: &ArchiveSourceConfig{},
+			},
+			wantErr:   true,
+			errSubstr: "archive.file is required",
+		},
+		{
+			name: "multiple sources not allowed - archive and git",
+			source: SourceConfig{
+				Archive: &ArchiveSourceConfig{
+					File: "https://example.com/fixtures.zip",
+				},
+				Git: &GitSourceV2{
+					Repo:    "https://github.com/test/repo",
+					Version: "v1.0.0",
+				},
+			},
+			wantErr:   true,
+			errSubstr: "cannot specify multiple sources",
+		},
 	}
 
 	for _, tt := range tests {
@@ -927,6 +967,15 @@ func TestSourceConfig_IsConfigured(t *testing.T) {
 			},
 			expected: true,
 		},
+		{
+			name: "archive source",
+			source: SourceConfig{
+				Archive: &ArchiveSourceConfig{
+					File: "https://example.com/fixtures.zip",
+				},
+			},
+			expected: true,
+		},
 	}
 
 	for _, tt := range tests {

pkg/executor/archive_source.go

@@ -0,0 +1,235 @@
+package executor
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/ethpandaops/benchmarkoor/pkg/config"
+	"github.com/sirupsen/logrus"
+)
+
+// ghArtifactURLPattern matches GitHub Actions artifact browser URLs:
+// https://github.com/{owner}/{repo}/actions/runs/{run_id}/artifacts/{artifact_id}
+var ghArtifactURLPattern = regexp.MustCompile(
+	`^https://github\.com/([^/]+/[^/]+)/actions/runs/\d+/artifacts/(\d+)$`,
+)
+
+// ArchiveSource downloads and extracts an archive file, then discovers tests
+// from the extracted contents using glob patterns.
+type ArchiveSource struct {
+	log         logrus.FieldLogger
+	cfg         *config.ArchiveSourceConfig
+	cacheDir    string
+	filter      string
+	githubToken string
+	basePath    string // temp directory where archive was extracted
+}
+
+// Prepare downloads (if URL) and extracts the archive, then discovers tests.
+func (s *ArchiveSource) Prepare(ctx context.Context) (*PreparedSource, error) {
+	// Create temp directory for extraction.
+	parentDir := s.cacheDir
+	if parentDir == "" {
+		parentDir = os.TempDir()
+	}
+
+	tmpDir, err := os.MkdirTemp(parentDir, "archive-*")
+	if err != nil {
+		return nil, fmt.Errorf("creating temp directory: %w", err)
+	}
+
+	s.basePath = tmpDir
+
+	// Determine the archive file path.
+	archivePath, err := s.resolveFile(ctx)
+	if err != nil {
+		_ = os.RemoveAll(s.basePath)
+		s.basePath = ""
+
+		return nil, fmt.Errorf("resolving archive file: %w", err)
+	}
+
+	// Detect format and extract.
+	if err := s.extractArchive(archivePath); err != nil {
+		_ = os.RemoveAll(s.basePath)
+		s.basePath = ""
+
+		return nil, fmt.Errorf("extracting archive: %w", err)
+	}
+
+	s.log.WithField("path", s.basePath).Info("Extracted archive")
+
+	return discoverTestsFromConfig(
+		s.basePath, s.cfg.PreRunSteps, s.cfg.Steps, s.filter, s.log,
+	)
+}
+
+// Cleanup removes the temporary extraction directory.
+func (s *ArchiveSource) Cleanup() error {
+	if s.basePath != "" {
+		return os.RemoveAll(s.basePath)
+	}
+
+	return nil
+}
+
+// GetSourceInfo returns source information for the suite summary.
+func (s *ArchiveSource) GetSourceInfo() (*SuiteSource, error) {
+	info := &ArchiveSourceInfo{
+		File:        s.cfg.File,
+		PreRunSteps: s.cfg.PreRunSteps,
+	}
+
+	if s.cfg.Steps != nil {
+		info.Steps = &SourceStepsGlobs{
+			Setup:   s.cfg.Steps.Setup,
+			Test:    s.cfg.Steps.Test,
+			Cleanup: s.cfg.Steps.Cleanup,
+		}
+	}
+
+	return &SuiteSource{Archive: info}, nil
+}
+
+// resolveFile returns the local path to the archive file. For URLs, it checks
+// the cache directory first and only downloads if the file is not already cached.
+func (s *ArchiveSource) resolveFile(ctx context.Context) (string, error) {
+	file := s.cfg.File
+
+	if strings.HasPrefix(file, "http://") || strings.HasPrefix(file, "https://") {
+		cachedPath := s.cachedArchivePath()
+
+		if _, err := os.Stat(cachedPath); err == nil {
+			s.log.WithFields(logrus.Fields{
+				"url":  file,
+				"path": cachedPath,
+			}).Info("Using cached archive")
+
+			return cachedPath, nil
+		}
+
+		s.log.WithField("url", file).Info("Downloading archive")
+
+		downloadURL, token := s.resolveDownloadURL(file)
+
+		// Download to a temp file first, then rename for atomic cache writes.
+		tmpPath := cachedPath + ".tmp"
+
+		if err := os.MkdirAll(filepath.Dir(cachedPath), 0755); err != nil {
+			return "", fmt.Errorf("creating cache directory: %w", err)
+		}
+
+		if err := downloadToFile(ctx, downloadURL, tmpPath, token, s.log); err != nil {
+			_ = os.Remove(tmpPath)
+
+			return "", err
+		}
+
+		if err := os.Rename(tmpPath, cachedPath); err != nil {
+			_ = os.Remove(tmpPath)
+
+			return "", fmt.Errorf("caching archive: %w", err)
+		}
+
+		s.log.WithField("path", cachedPath).Info("Archive cached")
+
+		return cachedPath, nil
+	}
+
+	// Local file path — resolve relative paths.
+	if !filepath.IsAbs(file) {
+		absPath, err := filepath.Abs(file)
+		if err != nil {
+			return "", fmt.Errorf("resolving path %q: %w", file, err)
+		}
+
+		file = absPath
+	}
+
+	if _, err := os.Stat(file); os.IsNotExist(err) {
+		return "", fmt.Errorf("archive file %q does not exist", file)
+	}
+
+	return file, nil
+}
+
+// cachedArchivePath returns a stable file path in the cache directory derived
+// from the configured URL, so repeated runs reuse the same downloaded file.
+func (s *ArchiveSource) cachedArchivePath() string {
+	hash := sha256.Sum256([]byte(s.cfg.File))
+	name := "archive-" + hex.EncodeToString(hash[:8])
+
+	cacheDir := s.cacheDir
+	if cacheDir == "" {
+		cacheDir = os.TempDir()
+	}
+
+	return filepath.Join(cacheDir, name)
+}
+
+// resolveDownloadURL converts browser URLs to API URLs where needed and returns
+// the appropriate auth token. For GitHub Actions artifact URLs, it converts to
+// the GitHub API download endpoint with bearer token auth.
+func (s *ArchiveSource) resolveDownloadURL(rawURL string) (string, string) {
+	matches := ghArtifactURLPattern.FindStringSubmatch(rawURL)
+	if matches != nil {
+		repo := matches[1]
+		artifactID := matches[2]
+		apiURL := fmt.Sprintf(
+			"https://api.github.com/repos/%s/actions/artifacts/%s/zip",
+			repo, artifactID,
+		)
+
+		s.log.WithFields(logrus.Fields{
+			"repo":        repo,
+			"artifact_id": artifactID,
+		}).Info("Detected GitHub artifact URL, using API endpoint")
+
+		if s.githubToken == "" {
+			s.log.Warn(
+				"GitHub token is required for artifact downloads. " +
+					"Set runner.github_token in config or " +
+					"BENCHMARKOOR_RUNNER_GITHUB_TOKEN env var",
+			)
+		}
+
+		return apiURL, s.githubToken
+	}
+
+	return rawURL, ""
+}
+
+// extractArchive detects the archive format and extracts it to the base path.
+// For ZIP archives, inner tarballs are also extracted automatically.
+func (s *ArchiveSource) extractArchive(archivePath string) error {
+	format, err := detectArchiveFormat(archivePath)
+	if err != nil {
+		return err
+	}
+
+	switch format {
+	case archiveFormatZip:
+		if err := extractZipFile(archivePath, s.basePath); err != nil {
+			return fmt.Errorf("extracting zip: %w", err)
+		}
+
+		// Auto-extract inner tarballs (e.g. GitHub Actions artifacts).
+		if err := extractInnerTarballs(s.basePath, s.log); err != nil {
+			return fmt.Errorf("extracting inner tarballs: %w", err)
+		}
+	case archiveFormatTarGz:
+		if err := extractTarGzFile(archivePath, s.basePath); err != nil {
+			return fmt.Errorf("extracting tar.gz: %w", err)
+		}
+	default:
+		return fmt.Errorf("unsupported archive format: %s", format)
+	}
+
+	return nil
+}