feat: support multi-part archive downloads (#193)

## Summary
- Adds a `parts` field to the archive source config as a
mutually-exclusive alternative to `file`
- Each part (URL or local path) is downloaded and cached independently,
then all parts are concatenated into a single cached archive before
extraction
- Useful when the archive exceeds per-asset upload size limits (e.g.
GitHub Releases)
- Per-part and combined files both use sha256-derived cache keys so
re-runs skip redundant downloads

### Example config
```yaml
runner:
  benchmark:
    tests:
      source:
        archive:
          parts:
            - https://github.com/org/repo/releases/download/v1.0.0/tests.tar.gz.00.part
            - https://github.com/org/repo/releases/download/v1.0.0/tests.tar.gz.01.part
          steps:
            test:
              - "testing/*.txt"
```

## Test plan
- [x] New unit tests for parts download + caching
(`TestArchiveSource_PrepareWithParts`)
- [x] New unit tests for local-path parts
(`TestArchiveSource_PrepareWithLocalParts`)
- [x] New unit tests for source info
(`TestArchiveSource_GetSourceInfo_Parts`)
- [x] Validation tests for mutual exclusivity
- [x] All existing archive tests still pass
- [x] Run with a real parts-based archive URL and verify extraction +
test discovery

Author: skylenet

config.example.yaml

@@ -134,6 +134,12 @@ runner:
     #     # GitHub Actions artifact URLs are auto-converted to API download endpoints.
     #     # archive:
     #     #   file: https://github.com/NethermindEth/gas-benchmarks/actions/runs/23847558369/artifacts/6222084759
+    #     #   # Alternative to `file`: a list of parts to download and concatenate.
+    #     #   # Useful when the archive is split across multiple files because of
+    #     #   # per-asset size limits. Mutually exclusive with `file`.
+    #     #   # parts:
+    #     #   #   - https://example.com/tests.tar.gz.00.part
+    #     #   #   - https://example.com/tests.tar.gz.01.part
     #     #   pre_run_steps:
     #     #     - "perf-devnet-3/gas-bump.txt"
     #     #     - "perf-devnet-3/funding.txt"

docs/configuration.md

@@ -325,12 +325,27 @@ tests:
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
-| `file` | string | Yes | Local path or URL to a ZIP or tar.gz archive. GitHub Actions artifact URLs are auto-converted to API endpoints |
+| `file` | string | One of `file`/`parts` | Local path or URL to a ZIP or tar.gz archive. GitHub Actions artifact URLs are auto-converted to API endpoints |
+| `parts` | []string | One of `file`/`parts` | Ordered list of local paths or URLs to concatenate into the final archive. Useful when the archive is split because of per-asset size limits. Mutually exclusive with `file` |
 | `pre_run_steps` | []string | No | Glob patterns for steps executed once before all tests |
 | `steps.setup` | []string | No | Glob patterns for setup phase files |
 | `steps.test` | []string | No | Glob patterns for test phase files |
 | `steps.cleanup` | []string | No | Glob patterns for cleanup phase files |
 
+**Multi-part archives:** when an archive is too large for a single asset upload, `parts` accepts an ordered list of URLs or local paths. All parts are downloaded (with caching) and concatenated into a single file before extraction:
+
+```yaml
+tests:
+  source:
+    archive:
+      parts:
+        - https://github.com/org/repo/releases/download/v1.0.0/tests.tar.gz.00.part
+        - https://github.com/org/repo/releases/download/v1.0.0/tests.tar.gz.01.part
+      steps:
+        test:
+          - "testing/*.txt"
+```
+
 ##### Opcode Source
 
 Optional external opcode metadata can be configured alongside the test source:

pkg/config/config.go

@@ -334,8 +334,13 @@ type LocalSourceV2 struct {
 
 // 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.
+// Alternatively, `parts` can be a list of paths/URLs that are concatenated in
+// order into the final archive (useful when the archive is split across
+// multiple files because of per-asset size limits). `file` and `parts` are
+// mutually exclusive.
 type ArchiveSourceConfig struct {
-	File        string       `yaml:"file" mapstructure:"file"`
+	File        string       `yaml:"file,omitempty" mapstructure:"file"`
+	Parts       []string     `yaml:"parts,omitempty" mapstructure:"parts"`
 	PreRunSteps []string     `yaml:"pre_run_steps,omitempty" mapstructure:"pre_run_steps"`
 	Steps       *StepsConfig `yaml:"steps,omitempty" mapstructure:"steps"`
 }
@@ -1145,8 +1150,15 @@ func (s *SourceConfig) Validate() error {
 	}
 
 	if s.Archive != nil {
-		if s.Archive.File == "" {
-			return fmt.Errorf("archive.file is required")
+		hasFile := s.Archive.File != ""
+		hasParts := len(s.Archive.Parts) > 0
+
+		if !hasFile && !hasParts {
+			return fmt.Errorf("archive.file or archive.parts is required")
+		}
+
+		if hasFile && hasParts {
+			return fmt.Errorf("archive.file and archive.parts are mutually exclusive")
 		}
 	}
 

pkg/config/config_test.go

@@ -628,12 +628,35 @@ func TestSourceConfig_Validate(t *testing.T) {
 			wantErr: false,
 		},
 		{
-			name: "archive missing file",
+			name: "archive missing file and parts",
 			source: SourceConfig{
 				Archive: &ArchiveSourceConfig{},
 			},
 			wantErr:   true,
-			errSubstr: "archive.file is required",
+			errSubstr: "archive.file or archive.parts is required",
+		},
+		{
+			name: "valid archive source with parts",
+			source: SourceConfig{
+				Archive: &ArchiveSourceConfig{
+					Parts: []string{
+						"https://example.com/fixtures.tar.gz.00.part",
+						"https://example.com/fixtures.tar.gz.01.part",
+					},
+				},
+			},
+			wantErr: false,
+		},
+		{
+			name: "archive file and parts are mutually exclusive",
+			source: SourceConfig{
+				Archive: &ArchiveSourceConfig{
+					File:  "https://example.com/fixtures.tar.gz",
+					Parts: []string{"https://example.com/fixtures.tar.gz.00.part"},
+				},
+			},
+			wantErr:   true,
+			errSubstr: "mutually exclusive",
 		},
 		{
 			name: "multiple sources not allowed - archive and git",

pkg/executor/archive_source.go

@@ -5,6 +5,7 @@ import (
 	"crypto/sha256"
 	"encoding/hex"
 	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 	"regexp"
@@ -91,6 +92,7 @@ func (s *ArchiveSource) Cleanup() error {
 func (s *ArchiveSource) GetSourceInfo() (*SuiteSource, error) {
 	info := &ArchiveSourceInfo{
 		File:        s.cfg.File,
+		Parts:       s.cfg.Parts,
 		PreRunSteps: s.cfg.PreRunSteps,
 	}
 
@@ -107,7 +109,13 @@ func (s *ArchiveSource) GetSourceInfo() (*SuiteSource, error) {
 
 // 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.
+// When the config uses `parts`, the parts are downloaded (with caching) and
+// concatenated into a single cached file.
 func (s *ArchiveSource) resolveFile(ctx context.Context) (string, error) {
+	if len(s.cfg.Parts) > 0 {
+		return s.resolvePartsFile(ctx)
+	}
+
 	file := s.cfg.File
 
 	if strings.HasPrefix(file, "http://") || strings.HasPrefix(file, "https://") {
@@ -181,6 +189,149 @@ func (s *ArchiveSource) cachedArchivePath() string {
 	return filepath.Join(cacheDir, name)
 }
 
+// resolvePartsFile downloads (with caching) all configured parts and
+// concatenates them in order into a single cached file, returning its path.
+// Local paths and URLs can be mixed freely in the parts list.
+func (s *ArchiveSource) resolvePartsFile(ctx context.Context) (string, error) {
+	cacheDir := s.cacheDir
+	if cacheDir == "" {
+		cacheDir = os.TempDir()
+	}
+
+	// Combined cache key is derived from the full ordered parts list so any
+	// change to the list produces a fresh combined file.
+	combined := sha256.Sum256([]byte(strings.Join(s.cfg.Parts, "\n")))
+	combinedPath := filepath.Join(cacheDir, "archive-parts-"+hex.EncodeToString(combined[:8]))
+
+	if _, err := os.Stat(combinedPath); err == nil {
+		s.log.WithField("path", combinedPath).Info("Using cached combined archive")
+
+		return combinedPath, nil
+	}
+
+	if err := os.MkdirAll(cacheDir, 0755); err != nil {
+		return "", fmt.Errorf("creating cache directory: %w", err)
+	}
+
+	// Resolve each part to a local file path (downloading URLs as needed).
+	partPaths := make([]string, 0, len(s.cfg.Parts))
+
+	for i, part := range s.cfg.Parts {
+		s.log.WithFields(logrus.Fields{
+			"part":  i + 1,
+			"total": len(s.cfg.Parts),
+			"ref":   part,
+		}).Info("Resolving archive part")
+
+		partPath, err := s.resolvePart(ctx, part, cacheDir)
+		if err != nil {
+			return "", fmt.Errorf("resolving part %d (%s): %w", i+1, part, err)
+		}
+
+		partPaths = append(partPaths, partPath)
+	}
+
+	// Concatenate all parts into a temporary file, then atomically rename.
+	tmpPath := combinedPath + ".tmp"
+
+	if err := concatFiles(tmpPath, partPaths); err != nil {
+		_ = os.Remove(tmpPath)
+
+		return "", fmt.Errorf("concatenating parts: %w", err)
+	}
+
+	if err := os.Rename(tmpPath, combinedPath); err != nil {
+		_ = os.Remove(tmpPath)
+
+		return "", fmt.Errorf("caching combined archive: %w", err)
+	}
+
+	s.log.WithField("path", combinedPath).Info("Combined archive parts")
+
+	return combinedPath, nil
+}
+
+// resolvePart resolves a single part reference (URL or local path) to a local
+// file path, downloading and caching remote parts in cacheDir.
+func (s *ArchiveSource) resolvePart(ctx context.Context, part, cacheDir string) (string, error) {
+	if strings.HasPrefix(part, "http://") || strings.HasPrefix(part, "https://") {
+		hash := sha256.Sum256([]byte(part))
+		cachedPath := filepath.Join(cacheDir, "archive-part-"+hex.EncodeToString(hash[:8]))
+
+		if _, err := os.Stat(cachedPath); err == nil {
+			s.log.WithFields(logrus.Fields{
+				"url":  part,
+				"path": cachedPath,
+			}).Info("Using cached archive part")
+
+			return cachedPath, nil
+		}
+
+		downloadURL, token := s.resolveDownloadURL(part)
+
+		tmpPath := cachedPath + ".tmp"
+
+		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 part: %w", err)
+		}
+
+		return cachedPath, nil
+	}
+
+	// Local file path — resolve relative paths.
+	if !filepath.IsAbs(part) {
+		absPath, err := filepath.Abs(part)
+		if err != nil {
+			return "", fmt.Errorf("resolving path %q: %w", part, err)
+		}
+
+		part = absPath
+	}
+
+	if _, err := os.Stat(part); os.IsNotExist(err) {
+		return "", fmt.Errorf("archive part %q does not exist", part)
+	}
+
+	return part, nil
+}
+
+// concatFiles concatenates src files (in order) into dst. dst is created (or
+// truncated) and written through a streamed copy so memory usage stays flat.
+func concatFiles(dst string, srcs []string) error {
+	out, err := os.Create(dst)
+	if err != nil {
+		return fmt.Errorf("creating %s: %w", dst, err)
+	}
+	defer out.Close() //nolint:errcheck
+
+	for _, src := range srcs {
+		in, err := os.Open(src) //nolint:gosec // trusted paths under our cache
+		if err != nil {
+			return fmt.Errorf("opening %s: %w", src, err)
+		}
+
+		if _, err := io.Copy(out, in); err != nil {
+			_ = in.Close()
+
+			return fmt.Errorf("copying %s: %w", src, err)
+		}
+
+		if err := in.Close(); err != nil {
+			return fmt.Errorf("closing %s: %w", src, err)
+		}
+	}
+
+	return out.Close()
+}
+
 // 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.