feat: Add upload to aws and retrieving results from aws

Author: tobidae-cb

Makefile

@@ -50,3 +50,13 @@ build-rbuilder:
 
 .PHONY: build-binaries
 build-binaries: build-reth build-geth build-rbuilder
+
+.PHONY: run-benchmark
+run-benchmark:
+	./bin/base-bench run --config ./configs/public/basic.yml --root-dir ./data-dir --output-dir ./output \
+        --reth-bin ./bin/op-reth --geth-bin ./bin/geth \
+        --enable-s3=true --s3-bucket base-benchmarking-results-dev
+
+.PHONY: upload-benchmark-results
+upload-benchmark-results:
+	./bin/base-bench export-to-cloud --output-dir ./output --s3-bucket base-benchmarking-results-dev

S3_Backend_Integration_README.md

@@ -0,0 +1,229 @@
+# AWS S3 Integration for Base Benchmarking
+
+This document describes the AWS S3 integration features added to the Base Benchmarking system.
+
+## Overview
+
+The benchmarking system now supports automatic upload of benchmark results to AWS S3, including:
+- Automatic upload after successful benchmark runs
+- Metadata synchronization with S3
+- Standalone export command for bulk uploads
+- Race condition handling for concurrent runs
+
+## Configuration
+
+### Environment Variables
+
+Set the following environment variables or CLI flags:
+
+```bash
+# Enable S3 upload
+export BASE_BENCH_ENABLE_S3=true
+
+# Specify S3 bucket name (follows pattern: base-benchmarking-results-{env})
+export BASE_BENCH_S3_BUCKET=base-benchmarking-results-dev
+```
+
+### AWS Credentials
+
+Ensure AWS credentials are configured using one of the following methods:
+
+1. **AWS Credentials File** - For development
+2. **Environment Variables**:
+   ```bash
+   export AWS_ACCESS_KEY_ID=your-access-key
+   export AWS_SECRET_ACCESS_KEY=your-secret-key
+   export AWS_REGION=us-east-1
+   ```
+
+## Usage
+
+### 1. Running Benchmarks with S3 Upload
+
+```bash
+# Run benchmarks with S3 upload enabled
+./bin/benchmark run \
+  --config ./configs/your-config.yml \
+  --output-dir ./output \
+  --enable-s3 \
+  --s3-bucket base-benchmarking-results-dev
+```
+
+When `--enable-s3` is set and a bucket is specified:
+- Successful test runs are automatically uploaded to S3
+- Each run gets a unique S3 path: `{run-id}/`
+- The `metadata.json` is synchronized with S3 after each run
+- Run metadata includes the `bucketPath` field pointing to S3 location
+
+### 2. Standalone Export Command
+
+Export an entire output directory to S3:
+
+```bash
+# Export existing output directory to S3
+./bin/benchmark export-to-cloud \
+  --output-dir ./output \
+  --s3-bucket base-benchmarking-results-dev
+```
+
+This command:
+- Reads the local `metadata.json` file
+- Downloads existing S3 `metadata.json` (if any)
+- Uploads all run directories to S3
+- Merges and uploads the updated metadata
+
+## S3 Structure
+
+### Bucket Organization
+
+```
+base-benchmarking-results-{env}/
+├── metadata.json                 # Root metadata file
+|-- test-1753974569311486/     # Run directory
+|   |-- test-1753974569311486-0/     # Run directory
+|   |   |-- metrics-sequencer.json
+|   |   |-- metrics-validator.json
+|   |   |-- result-sequencer.json
+|   |   |-- result-validator.json
+|   |   |-- logs-sequencer.gz
+|   |   |-- logs-validator.gz
+|   |-- test-1753974569311486-1/     # Another run directory
+|   |   |-- metrics-sequencer.json
+|   |   |-- metrics-validator.json
+|   |   |-- result-sequencer.json
+|   |   |-- result-validator.json
+|   |   |-- logs-sequencer.gz
+|   |   |-- logs-validator.gz
+|   |-- ...
+|-- ...
+```
+
+### Metadata Schema
+
+The `metadata.json` file contains:
+
+```json
+{
+  "runs": [
+    {
+      "id": "test-1753974569311486",
+      "sourceFile": "config.yml",
+      "outputDir": "test-1753974569311486-0",
+      "bucketPath": "test-1753974569311486-0/",
+      "testName": "Basic Test",
+      "testDescription": "Basic benchmarking test",
+      "testConfig": {...},
+      "result": {...},
+      "thresholds": {...},
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "createdAt": "2024-01-15T10:30:00Z"
+}
+```
+
+## Features
+
+### Race Condition Handling
+
+The system handles concurrent runs by:
+1. Downloading current S3 `metadata.json` before updates
+2. Merging new runs with existing metadata
+3. Uploading the combined metadata back to S3
+4. Using run IDs to prevent duplicates
+
+### Error Handling
+
+- S3 upload failures are logged as warnings and don't fail the benchmark
+- Missing S3 metadata is handled gracefully (creates new metadata)
+- Network issues are logged but don't interrupt benchmarking
+
+### File Upload
+
+- All files in the run output directory are uploaded
+- File paths are preserved relative to the run directory
+- Gzipped log files are supported
+- JSON result and metric files are uploaded
+
+## IAM Permissions
+
+Required S3 permissions for the benchmark system:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:ListBucket",
+        "s3:GetObject",
+        "s3:GetObjectVersion",
+        "s3:PutObject",
+        "s3:DeleteObject"
+      ],
+      "Resource": [
+        "arn:aws:s3:::base-benchmarking-results-*",
+        "arn:aws:s3:::base-benchmarking-results-*/*"
+      ]
+    }
+  ]
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **AWS Credentials Not Found**
+   - Ensure AWS credentials are properly configured
+   - Check IAM permissions for S3 access
+
+2. **Bucket Access Denied**
+   - Verify bucket name is correct
+   - Check IAM permissions include the specific bucket
+
+3. **Network Issues**
+   - S3 upload failures are logged but don't fail benchmarks
+   - Check AWS service status and network connectivity
+
+### Logs
+
+S3 operations are logged with the following patterns:
+- `"Uploading test results to S3"` - Starting upload
+- `"Successfully uploaded test results to S3"` - Upload completed
+- `"Failed to upload test results to S3"` - Upload failed
+- `"Syncing metadata with S3"` - Metadata sync starting
+- `"Successfully synced metadata with S3"` - Sync completed
+
+## Examples
+
+### Basic Benchmark Run with S3
+
+```bash
+./bin/benchmark run \
+  --config ./configs/basic.yml \
+  --output-dir ./output \
+  --enable-s3 \
+  --s3-bucket base-benchmarking-results-staging
+```
+
+### Export Existing Results
+
+```bash
+./bin/benchmark export-to-cloud \
+  --output-dir ./historical-results \
+  --s3-bucket base-benchmarking-results-prod
+```
+
+### Environment Variable Configuration
+
+```bash
+# Set environment variables
+export BASE_BENCH_ENABLE_S3=true
+export BASE_BENCH_S3_BUCKET=base-benchmarking-results-dev
+export BASE_BENCH_OUTPUT_DIR=./output
+
+# Run without CLI flags
+./bin/benchmark run --config ./configs/basic.yml
+```