Taskfile.yml

# Taskfile for Tellstone — https://taskfile.dev
# Run `task` (or `task --list`) to see available tasks.
version: '3'

vars:
  BIN: bin/tellstone
  BENCH_BIN: bin/benchmark

  # Build version info (overridden by CI / goreleaser via ldflags).
  VERSION: '{{.VERSION | default "0.0.0-dev"}}'
  COMMIT:
    sh: git rev-parse --short HEAD 2>/dev/null || echo "unknown"
  DATE:
    sh: date -u +%Y-%m-%dT%H:%M:%SZ
  LDFLAGS: >-
    -X github.com/Saxy/Tellstone/internal/version.Version={{.VERSION}}
    -X github.com/Saxy/Tellstone/internal/version.Commit={{.COMMIT}}
    -X github.com/Saxy/Tellstone/internal/version.Date={{.DATE}}

  # Ports — the binary listener uses a non-default port so it won't clash with an
  # IDE-launched instance on :9988. RESP uses the standard Redis port.
  BIN_PORT: '{{.BIN_PORT | default "19988"}}'
  RESP_PORT: '{{.RESP_PORT | default "6379"}}'

  # Core isolation settings (used on Linux)
  SRV_CORES: '{{.SRV_CORES | default "0-15"}}'
  SRV_PROCS: '{{.SRV_PROCS | default "16"}}'
  BENCH_CORES: '{{.BENCH_CORES | default "16-31"}}'

  # CROSS-PLATFORM MAGIC: Only prepend taskset if running on Linux
  TASKSET_SRV: '{{if eq OS "linux"}}taskset -c {{.SRV_CORES}}{{else}}{{end}}'
  TASKSET_BENCH: '{{if eq OS "linux"}}taskset -c {{.BENCH_CORES}}{{else}}{{end}}'

  # memtier workload knobs (override on the CLI, e.g. `task bench:resp PIPELINE=16`).
  THREADS: '{{.THREADS | default "4"}}'
  CONNS: '{{.CONNS | default "25"}}'
  DURATION: '{{.DURATION | default "10"}}'
  PIPELINE: '{{.PIPELINE | default "1"}}'
  RATIO: '{{.RATIO | default "1:10"}}'
  KEYSPACE: '{{.KEYSPACE | default "200000"}}'

tasks:
  default:
    desc: List available tasks
    cmds:
      - task --list
    silent: true

  # ---------- build ----------
  build:
    desc: Build the server binary into ./bin/tellstone
    cmds:
      - go build -ldflags "{{.LDFLAGS}}" -o {{.BIN}} ./cmd/tellstone
    sources:
      - "**/*.go"
    generates:
      - "{{.BIN}}"

  build:bench:
    desc: Build the native (binary-protocol) load generator into ./bin/benchmark
    cmds:
      - go build -o {{.BENCH_BIN}} ./cmd/benchmark

  build:all:
    desc: Build all binaries
    deps: [build, build:bench]

  # ---------- quality ----------
  fmt:
    desc: Format all Go code
    cmds:
      - go fmt ./...

  vet:
    desc: Run go vet
    cmds:
      - go vet ./...

  test:
    desc: Run the full test suite
    cmds:
      - go test ./...

  test:race:
    desc: Run the full test suite with the race detector
    cmds:
      - go test -race ./...

  check:
    desc: vet + race tests (run before committing)
    deps: [vet, test:race]

  clean:
    desc: Remove build artifacts
    cmds:
      - rm -rf bin

  # ---------- run ----------
  run:
    desc: Run the server in the foreground (binary protocol only)
    deps: [build]
    cmds:
      - TSD_ADDR=127.0.0.1:{{.BIN_PORT}} ./{{.BIN}}

  run:resp:
    desc: Run the server in the foreground with the RESP listener enabled
    deps: [build]
    cmds:
      - TSD_ADDR=127.0.0.1:{{.BIN_PORT}} TSD_ENABLE_RESP=true TSD_RESP_ADDR=127.0.0.1:{{.RESP_PORT}} ./{{.BIN}}

  # ---------- process management ----------
  kill:
    desc: "Find and kill stray Tellstone server processes, by port and by name. Linux + macOS (lsof/pgrep/pkill, no OS-specific tools). Vars: PORTS (default: 19988 6379 6060 — binary/RESP/pprof), NAME (default: bin/tellstone — deliberately specific, a bare 'tellstone' pattern would also match unrelated commands mentioning the project path)"
    vars:
      PORTS: '{{.PORTS | default "19988 6379 6060"}}'
      NAME: '{{.NAME | default "bin/tellstone"}}'
    cmds:
      - |
        set +e
        found=0
        if command -v lsof >/dev/null 2>&1; then
          for p in {{.PORTS}}; do
            pids=$(lsof -ti tcp:"$p" 2>/dev/null)
            if [ -n "$pids" ]; then
              echo "Port $p held by PID(s) $pids — killing"
              kill $pids 2>/dev/null
              found=1
            fi
          done
        else
          echo "lsof not found on this machine — skipping port lookup, falling back to name match only"
        fi
        matches=$(pgrep -f "{{.NAME}}" 2>/dev/null)
        if [ -n "$matches" ]; then
          echo "Process(es) matching '{{.NAME}}': $matches — killing"
          pkill -f "{{.NAME}}" 2>/dev/null
          found=1
        fi
        if [ "$found" = "0" ]; then
          echo "Nothing found — no process on ports [{{.PORTS}}] or matching '{{.NAME}}'."
        fi

  # ---------- benchmarks (self-contained: start pinned server, load, clean up) ----------
  bench:go:
    desc: "Run Go package benchmarks. Vars: PKG (default ./...), BENCH (default .), COUNT (default 1)"
    vars:
      PKG: '{{.PKG | default "./..."}}'
      BENCH: '{{.BENCH | default "."}}'
      COUNT: '{{.COUNT | default "1"}}'
    cmds:
      - go test -bench={{.BENCH}} -benchmem -count={{.COUNT}} -run='^$' {{.PKG}}
  bench:native:
    desc: Native binary-protocol benchmark, server & client pinned to disjoint cores (Linux only)
    deps: [ build, build:bench ]
    cmds:
      - |
        set -e
        {{.TASKSET_SRV}} env GOMAXPROCS={{.SRV_PROCS}} TSD_LOG_LEVEL=error \
          TSD_ADDR=127.0.0.1:{{.BIN_PORT}} ./{{.BIN}} >/tmp/tellstone-bench.log 2>&1 &
        SRV=$!; trap "kill $SRV 2>/dev/null || true" EXIT
        
        echo "Waiting for Tellstone (Port {{.BIN_PORT}})..."
        for i in {1..30}; do nc -z 127.0.0.1 {{.BIN_PORT}} && break; sleep 0.1; done
        nc -z 127.0.0.1 {{.BIN_PORT}} || { echo "Server failed to start:"; cat /tmp/tellstone-bench.log; exit 1; }
        
        {{.TASKSET_BENCH}} ./{{.BENCH_BIN}} -addr 127.0.0.1:{{.BIN_PORT}} \
          -c 32 -n 1000000 -read-ratio 0.95 -skew 1.5
  bench:resp:
    desc: "RESP latency benchmark via memtier. Vars: THREADS CONNS DURATION PIPELINE RATIO KEYSPACE"
    deps: [ build ]
    cmds:
      - |
        set -e
        command -v memtier_benchmark >/dev/null || { echo "memtier_benchmark not installed"; exit 1; }
        {{.TASKSET_SRV}} env GOMAXPROCS={{.SRV_PROCS}} TSD_LOG_LEVEL=error \
          TSD_ADDR=127.0.0.1:{{.BIN_PORT}} TSD_ENABLE_RESP=true TSD_RESP_ADDR=127.0.0.1:{{.RESP_PORT}} \
          ./{{.BIN}} >/tmp/tellstone-bench.log 2>&1 &
        SRV=$!; trap "kill $SRV 2>/dev/null || true" EXIT

        echo "Waiting for Tellstone RESP (Port {{.RESP_PORT}})..."
        for i in {1..30}; do nc -z 127.0.0.1 {{.RESP_PORT}} && break; sleep 0.1; done
        nc -z 127.0.0.1 {{.RESP_PORT}} || { echo "Server failed to start:"; cat /tmp/tellstone-bench.log; exit 1; }

        {{.TASKSET_BENCH}} memtier_benchmark -s 127.0.0.1 -p {{.RESP_PORT}} --protocol=redis \
          -t {{.THREADS}} -c {{.CONNS}} --test-time={{.DURATION}} --pipeline={{.PIPELINE}} \
          --ratio={{.RATIO}} --key-maximum={{.KEYSPACE}} --hide-histogram
  bench:resp:pipeline:
      desc: RESP throughput-ceiling benchmark (pipeline=16)
      cmds:
        - task: bench:resp
          vars: { PIPELINE: '16' }
  bench:resp:hits:
      desc: Realistic cache benchmark — preload the keyspace, then read-heavy (~100% hits)
      deps: [ build ]
      cmds:
        - |
          set -e
          command -v memtier_benchmark >/dev/null || { echo "memtier_benchmark not installed"; exit 1; }
          {{.TASKSET_SRV}} env GOMAXPROCS={{.SRV_PROCS}} TSD_LOG_LEVEL=error \
            TSD_ADDR=127.0.0.1:{{.BIN_PORT}} TSD_ENABLE_RESP=true TSD_RESP_ADDR=127.0.0.1:{{.RESP_PORT}} \
            ./{{.BIN}} >/tmp/tellstone-bench.log 2>&1 &
          SRV=$!; trap "kill $SRV 2>/dev/null || true" EXIT
          echo "Waiting for Tellstone RESP (Port {{.RESP_PORT}})..."
          for i in {1..30}; do nc -z 127.0.0.1 {{.RESP_PORT}} && break; sleep 0.1; done
          nc -z 127.0.0.1 {{.RESP_PORT}} || { echo "Server failed to start:"; cat /tmp/tellstone-bench.log; exit 1; }
          echo "== preload {{.KEYSPACE}} keys =="
          {{.TASKSET_BENCH}} memtier_benchmark -s 127.0.0.1 -p {{.RESP_PORT}} --protocol=redis \
            -t 1 -c 1 -n {{.KEYSPACE}} --ratio=1:0 --key-pattern=S:S \
            --key-minimum=1 --key-maximum={{.KEYSPACE}} --hide-histogram | grep -E "Sets|Totals"
          echo "== read-heavy (expect near-zero miss rate) =="
          {{.TASKSET_BENCH}} memtier_benchmark -s 127.0.0.1 -p {{.RESP_PORT}} --protocol=redis \
            -t {{.THREADS}} -c {{.CONNS}} --test-time={{.DURATION}} --pipeline={{.PIPELINE}} \
            --ratio=0:1 --key-maximum={{.KEYSPACE}} --hide-histogram
  bench:resp:precise:
    desc: "Reproducible baseline benchmark: 8 threads, 100 conns, pipeline 8, 90/10 read/write, with preload. Mirrors the pre-SN comparison table."
    deps: [ build ]
    cmds:
      - |
        set -e
        command -v memtier_benchmark >/dev/null || { echo "memtier_benchmark not installed"; exit 1; }
        {{.TASKSET_SRV}} env GOMAXPROCS=16 TSD_LOG_LEVEL=error \
          TSD_ADDR=127.0.0.1:{{.BIN_PORT}} TSD_ENABLE_RESP=true TSD_RESP_ADDR=127.0.0.1:{{.RESP_PORT}} \
          ./{{.BIN}} >/tmp/tellstone-bench.log 2>&1 &
        SRV=$!; trap "kill $SRV 2>/dev/null || true" EXIT
        echo "Waiting for Tellstone RESP (Port {{.RESP_PORT}})..."
        for i in {1..30}; do nc -z 127.0.0.1 {{.RESP_PORT}} && break; sleep 0.1; done
        nc -z 127.0.0.1 {{.RESP_PORT}} || { echo "Server failed to start:"; cat /tmp/tellstone-bench.log; exit 1; }

        echo "== preload 200000 keys =="
        {{.TASKSET_BENCH}} memtier_benchmark -s 127.0.0.1 -p {{.RESP_PORT}} --protocol=redis \
          -t 1 -c 1 -n 200000 --ratio=1:0 --key-pattern=S:S \
          --key-minimum=1 --key-maximum=200000 --hide-histogram | grep -E "Sets|Totals"

        echo "== read-heavy (expect near-zero miss rate) =="
        {{.TASKSET_BENCH}} memtier_benchmark -s 127.0.0.1 -p {{.RESP_PORT}} --protocol=redis \
          -t 8 -c 100 --test-time=10 --pipeline=8 \
          --ratio=1:9 --key-maximum=200000 --key-pattern=G:G \
          --key-stddev=50000 --hide-histogram

  bench:compare:
    desc: "Compare databases. Usage: task bench:compare TARGET=redis|valkey|tellstone [THREADS=...]"
    vars:
      TARGET: '{{.TARGET | default "tellstone"}}'
    cmds:
      - |
        set -e
        # Server startup logic
        case "{{.TARGET}}" in
          tellstone)
            echo "--- Starting Tellstone ---"
           sh -c 'export TSD_ADDR=127.0.0.1:{{.BIN_PORT}}; \
                   export TSD_ENABLE_RESP=true; \
                   export TSD_RESP_ADDR=127.0.0.1:{{.RESP_PORT}}; \
                   ./{{.BIN}} >/tmp/tellstone-bench.log 2>&1' &
            SRV=$! ;;
          redis)
            echo "--- Starting Redis ---"
            redis-server --port {{.RESP_PORT}} --save "" --appendonly no >/tmp/redis-bench.log 2>&1 &
            SRV=$! ;;
          valkey)
            echo "--- Starting Valkey ---"
            valkey-server --port {{.RESP_PORT}} --save "" --appendonly no >/tmp/valkey-bench.log 2>&1 &
            SRV=$! ;;
          *) echo "Unknown target: {{.TARGET}}"; exit 1 ;;
        esac
        
        trap "kill $SRV 2>/dev/null || true" EXIT
      
        # Wait for port to be ready
        for i in {1..30}; do nc -z 127.0.0.1 {{.RESP_PORT}} && break; sleep 0.5; done
        
        echo "Running memtier against {{.TARGET}}..."
        {{.TASKSET_BENCH}} memtier_benchmark -s 127.0.0.1 -p {{.RESP_PORT}} --protocol=redis \
          -t {{.THREADS}} -c {{.CONNS}} --test-time={{.DURATION}} --pipeline={{.PIPELINE}} \
          --ratio={{.RATIO}} --key-maximum={{.KEYSPACE}} --hide-histogram

  # ---------- profiling ----------
  # Two independent workflows, both driven by the stock Go toolchain (pprof / trace). Nothing
  # here assumes a specific core count, OS, or machine — every var is overridable on the CLI, so
  # this works the same on a laptop, CI runner, or a bigger benchmarking host.
  #
  #   1) profile:pkg + profile:view   — profile a package's Go benchmarks directly, no server.
  #   2) run:profiling + profile:live — profile the actual running server under real load
  #      generated from a second terminal (task bench:*, bin/benchmark, memtier_benchmark, ...).
  profile:pkg:
    desc: "Benchmark a package with CPU+mem profiling. Vars: PKG (default ./internal/storage/...), BENCH, COUNT, OUT"
    vars:
      PKG: '{{.PKG | default "./internal/storage/..."}}'
      BENCH: '{{.BENCH | default "."}}'
      COUNT: '{{.COUNT | default "1"}}'
      OUT: '{{.OUT | default "tmp/profile"}}'
    cmds:
      - mkdir -p {{.OUT}}
      - go test -bench={{.BENCH}} -benchmem -count={{.COUNT}} -run='^$' -cpuprofile={{.OUT}}/cpu.out -memprofile={{.OUT}}/mem.out {{.PKG}}
      - 'echo "CPU profile:  task profile:view FILE={{.OUT}}/cpu.out"'
      - 'echo "Mem profile:  task profile:view FILE={{.OUT}}/mem.out ARGS=-alloc_space"'

  profile:view:
    desc: "Open a saved pprof profile file in the browser. Vars: FILE (required), PORT (default 8081), ARGS (extra pprof flags, e.g. -alloc_space/-alloc_objects)"
    vars:
      FILE: '{{.FILE | default ""}}'
      PORT: '{{.PORT | default "8081"}}'
      ARGS: '{{.ARGS | default ""}}'
    cmds:
      - |
        set -e
        [ -n "{{.FILE}}" ] || { echo "FILE is required, e.g. task profile:view FILE=tmp/profile/cpu.out"; exit 1; }
        go tool pprof -http=:{{.PORT}} {{.ARGS}} {{.FILE}}

  run:profiling:
    desc: "Run the server in the foreground with live pprof enabled (mutex+block sampling, /debug/pprof on :6060). Generate load against it from a second terminal, then use profile:live."
    deps: [ build ]
    cmds:
      - TSD_ADDR=127.0.0.1:{{.BIN_PORT}} TSD_ENABLE_RESP=true TSD_RESP_ADDR=127.0.0.1:{{.RESP_PORT}} TSD_ENABLE_PROFILING=1 ./{{.BIN}}

  profile:live:
    desc: "Pull a profile from a server started via run:profiling and open it in the browser. Vars: KIND (cpu|heap|mutex|block|goroutine|allocs, default cpu), SECONDS (cpu only, default 30), PPROF_ADDR (default 127.0.0.1:6060), PORT (default 8081)"
    vars:
      KIND: '{{.KIND | default "cpu"}}'
      SECONDS: '{{.SECONDS | default "30"}}'
      PPROF_ADDR: '{{.PPROF_ADDR | default "127.0.0.1:6060"}}'
      PORT: '{{.PORT | default "8081"}}'
    cmds:
      - |
        set -e
        if [ "{{.KIND}}" = "cpu" ]; then
          URL="http://{{.PPROF_ADDR}}/debug/pprof/profile?seconds={{.SECONDS}}"
        else
          URL="http://{{.PPROF_ADDR}}/debug/pprof/{{.KIND}}"
        fi
        echo "Make sure load is running against the server (see README: Profiling) — an idle"
        echo "server produces an empty/uninteresting profile."
        echo "Fetching $URL ..."
        go tool pprof -http=:{{.PORT}} "$URL"

  profile:live:trace:
    desc: "Capture an execution trace from a server started via run:profiling and open it with go tool trace. Vars: SECONDS (default 5), PPROF_ADDR (default 127.0.0.1:6060), OUT (default tmp/trace.out)"
    vars:
      SECONDS: '{{.SECONDS | default "5"}}'
      PPROF_ADDR: '{{.PPROF_ADDR | default "127.0.0.1:6060"}}'
      OUT: '{{.OUT | default "tmp/trace.out"}}'
    cmds:
      - mkdir -p $(dirname {{.OUT}})
      - curl -s "http://{{.PPROF_ADDR}}/debug/pprof/trace?seconds={{.SECONDS}}" -o {{.OUT}}
      - go tool trace {{.OUT}}

  # ---------- podman ----------
  podman:build:
    desc: "Build dev container image. Vars: TAG (default: dev)"
    vars:
      TAG: '{{.TAG | default "dev"}}'
    cmds:
      - >-
        podman build
        --format docker
        --build-arg VERSION={{.VERSION}}
        --build-arg COMMIT={{.COMMIT}}
        --build-arg DATE={{.DATE}}
        -t ghcr.io/saxy/tellstone:{{.TAG}}
        -f container/Containerfile.dev .

  podman:up:
    desc: "Run Tellstone container. Vars: TAG (default: dev)"
    vars:
      TAG: '{{.TAG | default "dev"}}'
    cmds:
      - mkdir -p data
      - >-
        podman run -d --name tellstone-dev
        --rm
        -p 9988:9988
        -p 6379:6379
        -v ./data:/data:Z
        -e TSD_DATA_DIR=/data
        ghcr.io/saxy/tellstone:{{.TAG}}

  podman:down:
    desc: "Stop Tellstone container"
    cmds:
      - podman stop tellstone-dev 2>/dev/null || true

  podman:logs:
    desc: "Tail Tellstone container logs"
    cmds:
      - podman logs -f tellstone-dev

  podman:shell:
    desc: "Exec into running Tellstone container"
    cmds:
      - podman exec -it tellstone-dev /bin/sh || podman exec -it tellstone-dev /tellstone -h