feat: add upload benchmark suite for 10GB/100GB/1TB files

Introduce shell-based benchmark harness to measure upload performance
and memory footprint across large file sizes, with tool-agnostic JSON
results for future comparison against IPFS and BitTorrent.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Author: jessiebroke

benchmarks/.gitignore

@@ -1,2 +1,4 @@
 ceremony
 circuit_bench_*
+results/
+testdata/

benchmarks/archivist_bench.sh

@@ -0,0 +1,389 @@
+#!/usr/bin/env bash
+# archivist_bench.sh — Upload benchmark for archivist-node
+#
+# Usage:
+#   ./archivist_bench.sh [OPTIONS] [SIZE...]
+#
+# Options:
+#   --binary PATH       Path to archivist binary (default: ../build/archivist)
+#   --data-dir PATH     Node data directory (default: /tmp/archivist-bench-data)
+#   --api-port PORT     REST API port (default: 8080)
+#   --metrics-port PORT Metrics port (default: 8008)
+#   --repo-kind KIND    fs or sqlite (default: fs)
+#   --num-threads N     Worker threads, 0=auto (default: 0)
+#   --direct-io         Enable O_DIRECT
+#   --no-fsync          Disable fsync-file and fsync-dir
+#   --runs N            Repetitions per size (default: 1)
+#   --output-dir PATH   Results directory (default: ./results)
+#   --skip-build        Do not build the binary
+#
+# Sizes: 10GB, 100GB, 1TB (default: all three)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# shellcheck source=bench_common.sh
+source "${SCRIPT_DIR}/bench_common.sh"
+
+# ---------- defaults ----------
+BINARY="${REPO_ROOT}/build/archivist"
+DATA_DIR="/tmp/archivist-bench-data"
+API_PORT=8080
+METRICS_PORT=8008
+REPO_KIND="fs"
+NUM_THREADS=0
+DIRECT_IO=false
+NO_FSYNC=false
+RUNS=1
+OUTPUT_DIR="${SCRIPT_DIR}/results"
+SKIP_BUILD=false
+SIZES=()
+
+# ---------- parse arguments ----------
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --binary)       BINARY="$2"; shift 2 ;;
+    --data-dir)     DATA_DIR="$2"; shift 2 ;;
+    --api-port)     API_PORT="$2"; shift 2 ;;
+    --metrics-port) METRICS_PORT="$2"; shift 2 ;;
+    --repo-kind)    REPO_KIND="$2"; shift 2 ;;
+    --num-threads)  NUM_THREADS="$2"; shift 2 ;;
+    --direct-io)    DIRECT_IO=true; shift ;;
+    --no-fsync)     NO_FSYNC=true; shift ;;
+    --runs)         RUNS="$2"; shift 2 ;;
+    --output-dir)   OUTPUT_DIR="$2"; shift 2 ;;
+    --skip-build)   SKIP_BUILD=true; shift ;;
+    --help|-h)
+      sed -n '2,/^$/s/^# \?//p' "$0"
+      exit 0
+      ;;
+    10GB|100GB|1TB) SIZES+=("$1"); shift ;;
+    *)
+      log_error "Unknown option: $1"
+      exit 1
+      ;;
+  esac
+done
+
+# Default to all sizes if none specified
+if [[ ${#SIZES[@]} -eq 0 ]]; then
+  SIZES=(10GB 100GB 1TB)
+fi
+
+mkdir -p "$OUTPUT_DIR"
+
+# ---------- build ----------
+build_binary() {
+  if [[ "$SKIP_BUILD" == true ]]; then
+    log_info "Skipping build (--skip-build)"
+    return
+  fi
+
+  log_info "Building archivist (release)..."
+  mkdir -p "${REPO_ROOT}/build"
+
+  (
+    cd "$REPO_ROOT"
+    nim c \
+      -d:release \
+      -o:build/archivist \
+      archivist/archivist.nim
+  )
+
+  log_info "Build complete: ${BINARY}"
+}
+
+# ---------- node lifecycle ----------
+NODE_PID=""
+MEM_MON_PID=""
+
+cleanup() {
+  log_info "Cleaning up..."
+  if [[ -n "$MEM_MON_PID" ]] && kill -0 "$MEM_MON_PID" 2>/dev/null; then
+    kill "$MEM_MON_PID" 2>/dev/null || true
+    wait "$MEM_MON_PID" 2>/dev/null || true
+    MEM_MON_PID=""
+  fi
+  if [[ -n "$NODE_PID" ]] && kill -0 "$NODE_PID" 2>/dev/null; then
+    kill "$NODE_PID" 2>/dev/null || true
+    wait "$NODE_PID" 2>/dev/null || true
+    NODE_PID=""
+  fi
+}
+
+trap cleanup EXIT INT TERM
+
+start_node() {
+  local file_size_bytes=$1
+
+  # Storage quota = 120% of file size
+  local quota=$(( file_size_bytes * 12 / 10 ))
+
+  rm -rf "$DATA_DIR"
+  mkdir -p "$DATA_DIR"
+
+  local node_args=(
+    "--data-dir=${DATA_DIR}"
+    "--api-port=${API_PORT}"
+    "--metrics"
+    "--metrics-port=${METRICS_PORT}"
+    "--repo-kind=${REPO_KIND}"
+    "--storage-quota=${quota}"
+    "--block-ttl=0"
+    "--nat=none"
+    "--log-level=WARN"
+    "--num-threads=${NUM_THREADS}"
+  )
+
+  if [[ "$DIRECT_IO" == true ]]; then
+    node_args+=("--fs-direct-io")
+  fi
+
+  if [[ "$NO_FSYNC" == true ]]; then
+    node_args+=("--fs-fsync-file=false" "--fs-fsync-dir=false")
+  fi
+
+  log_info "Starting archivist node..."
+  log_info "  ${BINARY} ${node_args[*]}"
+
+  "$BINARY" "${node_args[@]}" &
+  NODE_PID=$!
+
+  # Wait for node readiness
+  log_info "Waiting for node to be ready (PID=${NODE_PID})..."
+  local deadline=$(( $(date +%s) + 60 ))
+  while true; do
+    if curl -sf "http://127.0.0.1:${API_PORT}/api/archivist/v1/debug/info" > /dev/null 2>&1; then
+      log_info "Node is ready"
+      break
+    fi
+    if ! kill -0 "$NODE_PID" 2>/dev/null; then
+      log_error "Node process died during startup"
+      return 1
+    fi
+    if (( $(date +%s) > deadline )); then
+      log_error "Node readiness timeout (60s)"
+      return 1
+    fi
+    sleep 0.5
+  done
+}
+
+stop_node() {
+  if [[ -n "$NODE_PID" ]] && kill -0 "$NODE_PID" 2>/dev/null; then
+    log_info "Stopping node (PID=${NODE_PID})..."
+    kill "$NODE_PID" 2>/dev/null || true
+    wait "$NODE_PID" 2>/dev/null || true
+    NODE_PID=""
+  fi
+  if [[ -d "$DATA_DIR" ]]; then
+    rm -rf "$DATA_DIR"
+  fi
+}
+
+# ---------- upload ----------
+upload_file() {
+  local test_file=$1
+  # Stream file via stdin to avoid curl buffering the whole thing
+  curl -s -X POST \
+    -H "Content-Type: application/octet-stream" \
+    -H "Expect:" \
+    --data-binary @- \
+    "http://127.0.0.1:${API_PORT}/api/archivist/v1/data" \
+    < "$test_file"
+}
+
+# ---------- main benchmark loop ----------
+run_benchmark() {
+  local label=$1 run_num=$2
+
+  log_info "=========================================="
+  log_info "Benchmark: ${label} — run ${run_num}/${RUNS}"
+  log_info "=========================================="
+
+  local file_size_bytes
+  file_size_bytes=$(size_label_to_bytes "$label")
+
+  # Ensure test file exists
+  local test_file
+  test_file=$(ensure_test_file "$label")
+  log_info "Test file: ${test_file}"
+
+  # Check disk space for stored data (1.2× file size)
+  local data_dir_parent
+  data_dir_parent=$(dirname "$DATA_DIR")
+  local needed_store=$(( file_size_bytes * 12 / 10 ))
+  check_disk_space "$needed_store" "$data_dir_parent"
+
+  # Start node
+  start_node "$file_size_bytes"
+
+  local run_tag="${label}_run${run_num}_$(date +%s)"
+  local mem_csv="${OUTPUT_DIR}/mem_${run_tag}.csv"
+  local metrics_before="${OUTPUT_DIR}/metrics_before_${run_tag}.txt"
+  local metrics_after="${OUTPUT_DIR}/metrics_after_${run_tag}.txt"
+  local result_json="${OUTPUT_DIR}/result_${run_tag}.json"
+
+  # Start memory monitor
+  MEM_MON_PID=$(start_memory_monitor "$NODE_PID" "$mem_csv" 1)
+  log_info "Memory monitor PID=${MEM_MON_PID} → ${mem_csv}"
+
+  # Snapshot Prometheus before
+  local metrics_url="http://127.0.0.1:${METRICS_PORT}/metrics"
+  scrape_prometheus_metrics "$metrics_url" "$metrics_before"
+
+  # Read CPU ticks before
+  local cpu_before
+  cpu_before=$(read_cpu_ticks "$NODE_PID")
+  local utime_before stime_before
+  utime_before=$(echo "$cpu_before" | awk '{print $1}')
+  stime_before=$(echo "$cpu_before" | awk '{print $2}')
+
+  # Upload
+  log_info "Starting upload of ${label}..."
+  local wall_start wall_end
+  wall_start=$(date +%s.%N)
+
+  local cid
+  cid=$(upload_file "$test_file")
+
+  wall_end=$(date +%s.%N)
+
+  if [[ -z "$cid" ]]; then
+    log_error "Upload returned empty CID"
+    stop_node
+    return 1
+  fi
+  log_info "Upload complete — CID: ${cid}"
+
+  # Read CPU ticks after
+  local cpu_after
+  cpu_after=$(read_cpu_ticks "$NODE_PID")
+  local utime_after stime_after
+  utime_after=$(echo "$cpu_after" | awk '{print $1}')
+  stime_after=$(echo "$cpu_after" | awk '{print $2}')
+
+  # Snapshot Prometheus after
+  scrape_prometheus_metrics "$metrics_url" "$metrics_after"
+
+  # Stop memory monitor
+  if [[ -n "$MEM_MON_PID" ]] && kill -0 "$MEM_MON_PID" 2>/dev/null; then
+    kill "$MEM_MON_PID" 2>/dev/null || true
+    wait "$MEM_MON_PID" 2>/dev/null || true
+    MEM_MON_PID=""
+  fi
+
+  # ---------- compute results ----------
+
+  # Wall time & throughput
+  local upload_time_s throughput_mbps
+  upload_time_s=$(awk "BEGIN {printf \"%.2f\", ${wall_end} - ${wall_start}}")
+  throughput_mbps=$(awk "BEGIN {
+    t = ${wall_end} - ${wall_start}
+    if (t > 0) printf \"%.1f\", (${file_size_bytes} / 1048576) / t
+    else print 0
+  }")
+
+  # Memory
+  local mem_stats peak_memory_mb avg_memory_mb
+  mem_stats=$(compute_memory_stats "$mem_csv")
+  peak_memory_mb=$(echo "$mem_stats" | awk '{print $1}')
+  avg_memory_mb=$(echo "$mem_stats" | awk '{print $2}')
+
+  # CPU
+  local utime_delta stime_delta cpu_user_s cpu_system_s
+  utime_delta=$(( utime_after - utime_before ))
+  stime_delta=$(( stime_after - stime_before ))
+  cpu_user_s=$(ticks_to_seconds "$utime_delta")
+  cpu_system_s=$(ticks_to_seconds "$stime_delta")
+
+  # Phase breakdown from Prometheus
+  local phase_read phase_hash phase_write phase_tree phase_proofs
+  phase_read=$(compute_delta_metric "$metrics_before" "$metrics_after" "archivist_upload_read_duration_seconds")
+  phase_hash=$(compute_delta_metric "$metrics_before" "$metrics_after" "archivist_upload_hash_duration_seconds")
+  phase_write=$(compute_delta_metric "$metrics_before" "$metrics_after" "archivist_upload_write_duration_seconds")
+  phase_tree=$(compute_delta_metric "$metrics_before" "$metrics_after" "archivist_upload_tree_duration_seconds")
+  phase_proofs=$(compute_delta_metric "$metrics_before" "$metrics_after" "archivist_upload_proofs_duration_seconds")
+
+  # Config JSON
+  local config_json
+  config_json=$(cat <<EOF
+{
+    "block_size": 65536,
+    "repo_kind": "${REPO_KIND}",
+    "num_threads": ${NUM_THREADS},
+    "direct_io": ${DIRECT_IO},
+    "no_fsync": ${NO_FSYNC}
+  }
+EOF
+  )
+
+  # System JSON
+  local system_json
+  system_json=$(collect_system_info)
+
+  # Print summary
+  log_info "--- Results: ${label} run ${run_num} ---"
+  log_info "  Upload time:   ${upload_time_s}s"
+  log_info "  Throughput:    ${throughput_mbps} MB/s"
+  log_info "  Peak memory:   ${peak_memory_mb} MB"
+  log_info "  Avg memory:    ${avg_memory_mb} MB"
+  log_info "  CPU user:      ${cpu_user_s}s"
+  log_info "  CPU system:    ${cpu_system_s}s"
+  log_info "  CID:           ${cid}"
+
+  # Write result JSON
+  write_result_json "$result_json" \
+    "archivist" "$label" "$file_size_bytes" \
+    "$upload_time_s" "$throughput_mbps" \
+    "$peak_memory_mb" "$avg_memory_mb" \
+    "$cpu_user_s" "$cpu_system_s" \
+    "$phase_read" "$phase_hash" "$phase_write" "$phase_tree" "$phase_proofs" \
+    "$cid" "$config_json" "$system_json"
+
+  # Write CSV row
+  local summary_csv="${OUTPUT_DIR}/summary.csv"
+  write_csv_header "$summary_csv"
+  write_csv_row "$summary_csv" \
+    "archivist" "$label" "$file_size_bytes" \
+    "$upload_time_s" "$throughput_mbps" \
+    "$peak_memory_mb" "$avg_memory_mb" \
+    "$cpu_user_s" "$cpu_system_s" \
+    "$phase_read" "$phase_hash" "$phase_write" "$phase_tree" "$phase_proofs" \
+    "$cid"
+
+  # Stop node & clean data dir
+  stop_node
+}
+
+# ---------- main ----------
+main() {
+  log_info "Archivist Upload Benchmark"
+  log_info "Sizes: ${SIZES[*]}"
+  log_info "Runs per size: ${RUNS}"
+  log_info "Output: ${OUTPUT_DIR}"
+
+  # Build
+  build_binary
+
+  if [[ ! -x "$BINARY" ]]; then
+    log_error "Binary not found or not executable: ${BINARY}"
+    exit 1
+  fi
+
+  # Run benchmarks
+  for label in "${SIZES[@]}"; do
+    for (( run = 1; run <= RUNS; run++ )); do
+      run_benchmark "$label" "$run"
+    done
+  done
+
+  log_info "=========================================="
+  log_info "All benchmarks complete!"
+  log_info "Results in: ${OUTPUT_DIR}"
+  log_info "=========================================="
+}
+
+main