Phase 4: make a multi-node replica able to start
CI / test (push) Failing after 53s

Placement and environment generation had landed early, which made multi-node
look further along than it was. A replica spanning nodes could not come up at
all, and all three reasons came down to assumptions that only hold on one node.

Not every rank serves HTTP. The agent health-checked every shard at its own
port, but only the leader answers; workers timed out, reported Failed and took
the replica with them. Engine.ServesHTTP now says which ranks serve, and a
worker is judged by staying alive. That is deliberately weaker evidence: the
replica's real readiness is the leader answering, which only happens once every
worker has joined.

A shard is not always one process. Engine.Commands returns a sequence — every
command but the last is a sidecar kept alive for the shard's lifetime and torn
down with it, and the last one's exit is the shard's. vLLM under Ray is why: the
leader runs a Ray head and then the server against it, while a worker runs only
the join and no vLLM process at all. RayCommand had been written and tested but
never called, so launch_mode: ray would have run vllm serve against a cluster
that did not exist. Sidecars are killed with the shard, because a Ray head left
behind holds the port the next replica needs.

Start order was backwards. Workers went first, on the theory that the head
should wait for them. Both engines put the rendezvous point on rank 0, so a
worker started first has nothing to connect to. vLLM's server blocks until the
Ray cluster has the GPUs it needs, so the leader can start immediately and waits
on its own. A command can now also require that rendezvous point to be listening
before the next starts, bounded by a timeout so a head that never appears fails
the shard instead of hanging it.

Stop was also killing only the engine, leaving sidecars behind.

None of this is verified against real engines — it is tested with stub
processes. The Ray sequencing, and which launch mode a given vLLM version wants,
can only be confirmed on hardware.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
ilkerandClaude Opus 5 committed 2026-09-16 06:20:03 +02:00
1 parent 75a8e76706
commit 1d1a6aebb0
11 files changed
+647 -125

No files matched your search

+198 -3
View File
@@ -5,6 +5,7 @@ import (
"errors"
"fmt"
"log/slog"
"net"
"os"
"path/filepath"
"strings"
@@ -42,9 +43,9 @@ func newSupervisor(t *testing.T) (*Supervisor, *scriptedHealth) {
return s, h
}
// shellCommand builds a Command running a shell script.
func shellCommand(script string) engines.Command {
return engines.Command{Path: "/bin/sh", Args: []string{"-c", script}, Env: os.Environ()}
// shellCommand builds the single-command sequence for a shell script.
func shellCommand(script string) []engines.Command {
return []engines.Command{{Path: "/bin/sh", Args: []string{"-c", script}, Env: os.Environ()}}
}
func waitState(t *testing.T, sh *Shard, want State, limit time.Duration) {
@@ -532,3 +533,197 @@ func TestCorruptStateFileIsCleanedUp(t *testing.T) {
t.Error("the corrupt state file was left behind")
}
}
// --- multi-process shards (plan §11, phase 4) ---
func TestSidecarRunsBeforeEngine(t *testing.T) {
// The Ray shape: a supporting process starts first and keeps running, then
// the engine starts against it.
s, _ := newSupervisor(t)
dir := t.TempDir()
order := filepath.Join(dir, "order")
// Each writes to the order file and to stdout: the file records the
// sequence, stdout exercises per-process log attribution.
cmds := []engines.Command{
{Name: "sidecar", Path: "/bin/sh", Args: []string{"-c",
fmt.Sprintf("echo sidecar >> %s; echo hello-from-sidecar; sleep 30", order)}, Env: os.Environ()},
{Name: "engine", Path: "/bin/sh", Args: []string{"-c",
fmt.Sprintf("echo engine >> %s; echo hello-from-engine; sleep 30", order)}, Env: os.Environ()},
}
sh, err := s.Start(t.Context(), "a", engines.ShardSpec{}, cmds)
if err != nil {
t.Fatal(err)
}
deadline := time.Now().Add(3 * time.Second)
for time.Now().Before(deadline) {
if b, err := os.ReadFile(order); err == nil && strings.Count(string(b), "\n") == 2 {
if got := strings.Fields(string(b)); got[0] != "sidecar" || got[1] != "engine" {
t.Fatalf("start order was %v", got)
}
break
}
time.Sleep(20 * time.Millisecond)
}
// The shard's pid is the engine's, not the sidecar's: the engine's exit is
// what ends the shard.
if sh.Status().PID == 0 {
t.Fatal("no engine pid recorded")
}
// Both processes appear in one log tail, distinguishable by prefix.
deadline = time.Now().Add(3 * time.Second)
for time.Now().Before(deadline) {
logs := strings.Join(sh.Logs(20), "\n")
if strings.Contains(logs, "[sidecar] hello-from-sidecar") &&
strings.Contains(logs, "[engine] hello-from-engine") {
return
}
time.Sleep(20 * time.Millisecond)
}
t.Errorf("output is not attributed per process:\n%s", strings.Join(sh.Logs(20), "\n"))
}
func TestStopKillsSidecar(t *testing.T) {
// A Ray head left behind holds the port the next replica needs, and would
// let a later shard join a cluster that serves nothing.
s, _ := newSupervisor(t)
dir := t.TempDir()
marker := filepath.Join(dir, "sidecar.pid")
cmds := []engines.Command{
{Name: "sidecar", Path: "/bin/sh", Args: []string{"-c",
fmt.Sprintf("echo $$ > %s; sleep 30", marker)}, Env: os.Environ()},
{Name: "engine", Path: "/bin/sh", Args: []string{"-c", "sleep 30"}, Env: os.Environ()},
}
if _, err := s.Start(t.Context(), "a", engines.ShardSpec{}, cmds); err != nil {
t.Fatal(err)
}
var sidePID int
deadline := time.Now().Add(3 * time.Second)
for time.Now().Before(deadline) {
if b, err := os.ReadFile(marker); err == nil {
if _, err := fmt.Sscanf(strings.TrimSpace(string(b)), "%d", &sidePID); err == nil && sidePID > 0 {
break
}
}
time.Sleep(10 * time.Millisecond)
}
if sidePID == 0 {
t.Fatal("the sidecar never started")
}
if err := s.Stop(t.Context(), "a"); err != nil {
t.Fatal(err)
}
deadline = time.Now().Add(3 * time.Second)
for time.Now().Before(deadline) {
if !processAlive(sidePID) {
return
}
time.Sleep(20 * time.Millisecond)
}
t.Errorf("the sidecar (%d) survived the stop and still holds its port", sidePID)
}
func TestSidecarFailureFailsTheShard(t *testing.T) {
s, _ := newSupervisor(t)
cmds := []engines.Command{
{Name: "sidecar", Path: "/nonexistent/binary", Env: os.Environ()},
{Name: "engine", Path: "/bin/sh", Args: []string{"-c", "sleep 30"}, Env: os.Environ()},
}
sh, err := s.Start(t.Context(), "a", engines.ShardSpec{}, cmds)
if err == nil {
t.Fatal("a shard whose sidecar could not start was reported healthy")
}
if !strings.Contains(err.Error(), "sidecar") {
t.Errorf("the error does not identify the sidecar: %v", err)
}
if sh.Status().State != Failed {
t.Errorf("state=%s", sh.Status().State)
}
}
func TestWaitForLeaderPortBlocksUntilListening(t *testing.T) {
// A Ray worker cannot join a head that is not up, and the leader's server
// cannot claim GPUs from a cluster that does not exist yet.
s, _ := newSupervisor(t)
s.cfg.RendezvousTimeout = 5 * time.Second
ln, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
port := ln.Addr().(*net.TCPAddr).Port
_ = ln.Close() // nothing listening yet
spec := engines.ShardSpec{LeaderAddr: "127.0.0.1", LeaderPort: port}
cmds := []engines.Command{
{Name: "sidecar", Path: "/bin/sh", Args: []string{"-c",
fmt.Sprintf("sleep 0.4; nc -l %d", port)}, Env: os.Environ(),
WaitForLeaderPort: true},
{Name: "engine", Path: "/bin/sh", Args: []string{"-c", "sleep 30"}, Env: os.Environ()},
}
start := time.Now()
if _, err := s.Start(t.Context(), "a", spec, cmds); err != nil {
t.Skipf("nc is unavailable for the rendezvous stub: %v", err)
}
if d := time.Since(start); d < 300*time.Millisecond {
t.Errorf("the engine started after %v, before the rendezvous point was listening", d)
}
}
func TestRendezvousTimeout(t *testing.T) {
// Nothing ever listens, so the shard must fail rather than hang forever.
s, _ := newSupervisor(t)
s.cfg.RendezvousTimeout = 300 * time.Millisecond
spec := engines.ShardSpec{LeaderAddr: "127.0.0.1", LeaderPort: 1}
cmds := []engines.Command{
{Name: "sidecar", Path: "/bin/sh", Args: []string{"-c", "sleep 30"},
Env: os.Environ(), WaitForLeaderPort: true},
{Name: "engine", Path: "/bin/sh", Args: []string{"-c", "sleep 30"}, Env: os.Environ()},
}
if _, err := s.Start(t.Context(), "a", spec, cmds); err == nil {
t.Fatal("the shard did not fail when the rendezvous point never appeared")
}
}
func TestWaitAliveForNonServingRank(t *testing.T) {
// A worker has no endpoint to poll, so staying up is the only evidence
// available. This is what stopped multi-node replicas coming up at all.
s, _ := newSupervisor(t)
s.cfg.AliveGrace = 150 * time.Millisecond
sh, err := s.Start(t.Context(), "a", engines.ShardSpec{Rank: 1}, shellCommand("sleep 30"))
if err != nil {
t.Fatal(err)
}
if err := s.WaitAlive(t.Context(), sh); err != nil {
t.Fatal(err)
}
if got := sh.Status().State; got != Ready {
t.Errorf("state=%s", got)
}
}
func TestWaitAliveFailsOnEarlyExit(t *testing.T) {
s, _ := newSupervisor(t)
s.cfg.AliveGrace = 2 * time.Second
sh, err := s.Start(t.Context(), "a", engines.ShardSpec{Rank: 1}, shellCommand("exit 1"))
if err != nil {
t.Fatal(err)
}
start := time.Now()
if err := s.WaitAlive(t.Context(), sh); err == nil {
t.Fatal("a worker that died immediately was reported ready")
}
if d := time.Since(start); d > 1500*time.Millisecond {
t.Errorf("waited %v for a process that had already exited", d)
}
}