puma-plus-core 0.1.0

data/go/internal/frontend/protocol_test.go

@@ -0,0 +1,391 @@
+package frontend
+
+import (
+	"context"
+	"crypto/tls"
+	"fmt"
+	"io"
+	"log"
+	"net"
+	"net/http"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/evanphx/puma-plus/internal/queue"
+	"github.com/evanphx/puma-plus/internal/wire"
+	"github.com/quic-go/quic-go"
+	"github.com/quic-go/quic-go/http3"
+	"golang.org/x/net/http2"
+)
+
+// TestProtocolsProduceIdenticalEnv is the load-bearing test for the whole
+// architecture.
+//
+// An h1 request, an h2 stream and an h3 stream arrive over three entirely
+// different transports and three different protocol state machines. The claim
+// is that all three reduce to the same REQUEST frame, so Ruby never learns which
+// one it was and the protocol story costs the Ruby side nothing.
+//
+// The test checks that literally: it captures the env each protocol produces and
+// asserts they are identical except for SERVER_PROTOCOL and the transport-level
+// fields that are *supposed* to differ.
+func TestProtocolsProduceIdenticalEnv(t *testing.T) {
+	var mu sync.Mutex
+	envs := map[string]map[string]string{}
+	var lastVersion uint8
+
+	reg := queue.NewRegistry(16)
+	newProtoWorker(t, reg, func(meta wire.RequestMeta, env map[string]string) {
+		mu.Lock()
+		defer mu.Unlock()
+		lastVersion = meta.HTTPVersion
+		envs["pending"] = env
+	})
+	time.Sleep(20 * time.Millisecond)
+
+	h := NewHandler(reg, Options{
+		Logger:         log.New(io.Discard, "", 0),
+		AcquireTimeout: 5 * time.Second,
+	})
+
+	cert, err := DevCertificate("localhost")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Bring up all three frontends on ephemeral ports.
+	h1Addr := freeTCP(t)
+	tlsAddr := freeTCP(t)
+	h3Addr := freeUDP(t)
+
+	ls, err := Start(ListenerOptions{
+		Handler: h, Logger: log.New(io.Discard, "", 0),
+		Addr: h1Addr, TLSAddr: tlsAddr, H3Addr: h3Addr, Cert: cert,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ls.Shutdown(context.Background())
+	time.Sleep(300 * time.Millisecond) // let the listeners bind
+
+	type probe struct {
+		name    string
+		client  *http.Client
+		url     string
+		wantVer uint8
+		proto   string
+	}
+	probes := []probe{
+		{
+			name: "h1", proto: "HTTP/1.1", wantVer: wire.HTTP11,
+			client: &http.Client{Transport: &http.Transport{ForceAttemptHTTP2: false}},
+			url:    "http://" + h1Addr + "/path?a=1",
+		},
+		{
+			name: "h2", proto: "HTTP/2.0", wantVer: wire.HTTP2,
+			client: &http.Client{Transport: &http2.Transport{
+				TLSClientConfig: &tls.Config{InsecureSkipVerify: true, NextProtos: []string{"h2"}},
+			}},
+			url: "https://" + tlsAddr + "/path?a=1",
+		},
+		{
+			name: "h3", proto: "HTTP/3.0", wantVer: wire.HTTP3,
+			client: &http.Client{Transport: &http3.Transport{
+				TLSClientConfig: &tls.Config{InsecureSkipVerify: true, NextProtos: []string{http3.NextProtoH3}},
+				QUICConfig:      &quic.Config{MaxIdleTimeout: 10 * time.Second},
+			}},
+			url: "https://" + h3Addr + "/path?a=1",
+		},
+	}
+
+	captured := map[string]map[string]string{}
+	versions := map[string]uint8{}
+
+	for _, p := range probes {
+		req, err := http.NewRequest(http.MethodGet, p.url, nil)
+		if err != nil {
+			t.Fatalf("%s: %v", p.name, err)
+		}
+		req.Header.Set("User-Agent", "proto-probe")
+		req.Header.Set("X-Marker", "same-for-all")
+
+		resp, err := p.client.Do(req)
+		if err != nil {
+			t.Fatalf("%s request failed: %v", p.name, err)
+		}
+		io.Copy(io.Discard, resp.Body)
+		resp.Body.Close()
+
+		if resp.StatusCode != 200 {
+			t.Fatalf("%s: status %d", p.name, resp.StatusCode)
+		}
+
+		mu.Lock()
+		captured[p.name] = envs["pending"]
+		versions[p.name] = lastVersion
+		mu.Unlock()
+
+		if got := versions[p.name]; got != p.wantVer {
+			t.Errorf("%s: http_version byte = %d, want %d", p.name, got, p.wantVer)
+		}
+		if got := captured[p.name]["SERVER_PROTOCOL"]; got != p.proto {
+			t.Errorf("%s: SERVER_PROTOCOL = %q, want %q", p.name, got, p.proto)
+		}
+	}
+
+	// Fields that legitimately differ between transports: the protocol name, the
+	// port each listener bound, the scheme (h2/h3 are TLS), and the client's
+	// ephemeral source port inside Host.
+	transportSpecific := map[string]bool{
+		"SERVER_PROTOCOL":      true,
+		"SERVER_PORT":          true,
+		"HTTP_HOST":            true,
+		"rack.url_scheme":      true,
+		"HTTP_ACCEPT_ENCODING": true, // set by each client library differently
+	}
+
+	base := captured["h1"]
+	for _, name := range []string{"h2", "h3"} {
+		other := captured[name]
+		for k, v := range base {
+			if transportSpecific[k] {
+				continue
+			}
+			if other[k] != v {
+				t.Errorf("env[%q] differs: h1=%q %s=%q -- the protocol must not "+
+					"leak into the Rack env", k, v, name, other[k])
+			}
+		}
+		for k := range other {
+			if transportSpecific[k] {
+				continue
+			}
+			if _, ok := base[k]; !ok {
+				t.Errorf("%s produced env key %q that h1 did not", name, k)
+			}
+		}
+	}
+
+	t.Logf("h1/h2/h3 all produced identical envs apart from SERVER_PROTOCOL (%q/%q/%q) and transport fields",
+		captured["h1"]["SERVER_PROTOCOL"], captured["h2"]["SERVER_PROTOCOL"],
+		captured["h3"]["SERVER_PROTOCOL"])
+}
+
+// TestH2CServesHTTP2OnCleartext checks the h2c path separately, since it is the
+// one that isolates HTTP/2 framing costs from TLS handshake costs.
+func TestH2CServesHTTP2OnCleartext(t *testing.T) {
+	var gotProto string
+	var mu sync.Mutex
+
+	reg := queue.NewRegistry(8)
+	newProtoWorker(t, reg, func(_ wire.RequestMeta, env map[string]string) {
+		mu.Lock()
+		gotProto = env["SERVER_PROTOCOL"]
+		mu.Unlock()
+	})
+	time.Sleep(20 * time.Millisecond)
+
+	h := NewHandler(reg, Options{Logger: log.New(io.Discard, "", 0), AcquireTimeout: 3 * time.Second})
+	addr := freeTCP(t)
+	ls, err := Start(ListenerOptions{
+		Handler: h, Logger: log.New(io.Discard, "", 0), Addr: addr, H2C: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ls.Shutdown(context.Background())
+	time.Sleep(200 * time.Millisecond)
+
+	client := &http.Client{Transport: &http2.Transport{
+		AllowHTTP: true,
+		DialTLSContext: func(ctx context.Context, network, a string, _ *tls.Config) (net.Conn, error) {
+			return (&net.Dialer{}).DialContext(ctx, network, a)
+		},
+	}}
+	resp, err := client.Get("http://" + addr + "/")
+	if err != nil {
+		t.Fatal(err)
+	}
+	io.Copy(io.Discard, resp.Body)
+	resp.Body.Close()
+
+	if resp.Proto != "HTTP/2.0" {
+		t.Errorf("client negotiated %s, want HTTP/2.0", resp.Proto)
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if gotProto != "HTTP/2.0" {
+		t.Errorf("worker saw SERVER_PROTOCOL %q, want HTTP/2.0", gotProto)
+	}
+}
+
+// TestH2MultiplexesConcurrentStreams checks the property h1 cannot have: many
+// concurrent requests over ONE connection. Under h1 these would serialise or
+// need N connections.
+func TestH2MultiplexesConcurrentStreams(t *testing.T) {
+	reg := queue.NewRegistry(32)
+	// Several workers so requests can genuinely run in parallel.
+	for i := 0; i < 8; i++ {
+		newSlowWorker(t, reg, 100*time.Millisecond)
+	}
+	time.Sleep(50 * time.Millisecond)
+
+	h := NewHandler(reg, Options{Logger: log.New(io.Discard, "", 0), AcquireTimeout: 5 * time.Second})
+	cert, _ := DevCertificate("localhost")
+	addr := freeTCP(t)
+	ls, err := Start(ListenerOptions{
+		Handler: h, Logger: log.New(io.Discard, "", 0), TLSAddr: addr, Cert: cert,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ls.Shutdown(context.Background())
+	time.Sleep(200 * time.Millisecond)
+
+	tr := &http2.Transport{
+		TLSClientConfig: &tls.Config{InsecureSkipVerify: true, NextProtos: []string{"h2"}},
+	}
+	client := &http.Client{Transport: tr}
+
+	// Warm the connection so the handshake is not counted.
+	if resp, err := client.Get("https://" + addr + "/"); err == nil {
+		io.Copy(io.Discard, resp.Body)
+		resp.Body.Close()
+	}
+
+	const n = 8
+	start := time.Now()
+	var wg sync.WaitGroup
+	errs := make(chan error, n)
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			resp, err := client.Get("https://" + addr + "/")
+			if err != nil {
+				errs <- err
+				return
+			}
+			io.Copy(io.Discard, resp.Body)
+			resp.Body.Close()
+		}()
+	}
+	wg.Wait()
+	close(errs)
+	for err := range errs {
+		t.Fatalf("concurrent h2 request failed: %v", err)
+	}
+
+	elapsed := time.Since(start)
+	// Serialised, 8 x 100ms would be 800ms. Multiplexed over one connection with
+	// 8 workers it should be near 100ms.
+	if elapsed > 400*time.Millisecond {
+		t.Errorf("8 concurrent streams took %s; expected them to multiplex over one connection", elapsed)
+	}
+	t.Logf("8 concurrent 100ms requests over a single h2 connection completed in %s", elapsed)
+}
+
+// --- helpers -------------------------------------------------------------
+
+// newProtoWorker registers a worker that reports the env it received.
+func newProtoWorker(t *testing.T, reg *queue.Registry, onReq func(wire.RequestMeta, map[string]string)) {
+	t.Helper()
+	fds, err := makeSocketPair()
+	if err != nil {
+		t.Fatal(err)
+	}
+	reg.Add(queue.NewConn(fds[0], 4242, 0, 0))
+	t.Cleanup(func() { fds[1].Close() })
+
+	go func() {
+		r := wire.NewReader(fds[1])
+		w := wire.NewWriter(fds[1])
+		for {
+			typ, payload, err := r.ReadFrame()
+			if err != nil || typ != wire.TypeRequest {
+				return
+			}
+			meta, rest, err := wire.DecodeRequestMeta(payload)
+			if err != nil {
+				return
+			}
+			pairs, _, err := wire.DecodeKV(rest)
+			if err != nil {
+				return
+			}
+			env := make(map[string]string, len(pairs))
+			for _, p := range pairs {
+				env[string(p.Key)] = string(p.Value)
+			}
+			onReq(meta, env)
+
+			resp := wire.AppendKV([]byte{0x00, 0xc8},
+				[]wire.Pair{{Key: []byte("content-type"), Value: []byte("text/plain")}})
+			if w.WriteFrame(wire.TypeResponse, resp) != nil {
+				return
+			}
+			if w.WriteFrame(wire.TypeRespChunk, []byte("ok")) != nil {
+				return
+			}
+			end := wire.AppendRespEndMeta(nil, wire.RespEndMeta{ServiceNs: 1000})
+			if w.WriteFrame(wire.TypeRespEnd, wire.AppendKV(end, nil)) != nil {
+				return
+			}
+		}
+	}()
+}
+
+func newSlowWorker(t *testing.T, reg *queue.Registry, d time.Duration) {
+	t.Helper()
+	fds, err := makeSocketPair()
+	if err != nil {
+		t.Fatal(err)
+	}
+	reg.Add(queue.NewConn(fds[0], 4243, 0, 0))
+	t.Cleanup(func() { fds[1].Close() })
+
+	go func() {
+		r := wire.NewReader(fds[1])
+		w := wire.NewWriter(fds[1])
+		for {
+			typ, _, err := r.ReadFrame()
+			if err != nil || typ != wire.TypeRequest {
+				return
+			}
+			time.Sleep(d)
+			resp := wire.AppendKV([]byte{0x00, 0xc8}, nil)
+			if w.WriteFrame(wire.TypeResponse, resp) != nil {
+				return
+			}
+			end := wire.AppendRespEndMeta(nil, wire.RespEndMeta{ServiceNs: uint64(d)})
+			if w.WriteFrame(wire.TypeRespEnd, wire.AppendKV(end, nil)) != nil {
+				return
+			}
+		}
+	}()
+}
+
+func freeTCP(t *testing.T) string {
+	t.Helper()
+	l, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	addr := l.Addr().String()
+	l.Close()
+	return addr
+}
+
+func freeUDP(t *testing.T) string {
+	t.Helper()
+	c, err := net.ListenPacket("udp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	addr := c.LocalAddr().String()
+	c.Close()
+	return addr
+}
+
+var _ = fmt.Sprintf

data/go/internal/frontend/ractor_shepherd.go

@@ -0,0 +1,160 @@
+package frontend
+
+import (
+	"log"
+	"sync"
+
+	"github.com/evanphx/puma-plus/internal/queue"
+)
+
+// RactorShepherd actuates scaling when capacity is Ractors rather than worker
+// processes.
+//
+// It satisfies the same control.Shepherd interface as the worker-mode adapter,
+// so the controller, the decision function, the decision log and the replay
+// tests are all untouched. What changes is only how "make it four" is carried
+// out, never how the decision to say so was reached.
+//
+// The asymmetry is the interesting part.
+//
+//	grow   -- SET_SLOTS to the Ruby process, which calls Ractor.new
+//	shrink -- GOAWAY an idle connection directly from Go, no Ruby involved
+//
+// Growing must go through Ruby because only Ruby can create a Ractor. Shrinking
+// cannot go through Ruby, because a Ractor cannot be killed from outside and
+// the one we want to stop is blocked reading its socket. What rescues this is
+// that GOAWAY already meant exactly the right thing -- "drain this idle slot,
+// the thread exits" -- and WorkerThread already handled it, so scale-down
+// needed no new protocol and no new Ruby code at all. A Ractor simply ends when
+// its only thread returns.
+//
+// Go could not do this for a forked worker: it can close a process's sockets
+// but not make the process exit, which is why worker mode routes retirement
+// through the shepherd and a TERM. Ractor mode is the case where owning the
+// queue lets Go retire capacity by itself.
+type RactorShepherd struct {
+	acc    *Acceptor
+	reg    *queue.Registry
+	logger *log.Logger
+
+	// perUnit is how many Ractors make up one unit of capacity as the
+	// controller counts them.
+	//
+	// This exists because the controller adds ONE unit per decision, and a
+	// decision costs a confirmation window (three 1s ticks) that no actuator can
+	// shorten. In fork mode a unit is a worker process carrying ThreadsPerWorker
+	// threads, so one decision buys five slots. Measured with a unit of one
+	// Ractor, the same controller took 25 decisions to reach capacity 30 where
+	// forking took 5, and lost on latency by a factor of 300 despite spawning
+	// ~125x faster per spawn. Actuator granularity dominated actuator latency
+	// completely.
+	perUnit int
+
+	mu     sync.Mutex
+	target int // in units, not Ractors
+}
+
+// NewRactorShepherd wires the control connection to the queue registry.
+//
+// Takes the Acceptor rather than a ShepherdConn because the Ruby process dials
+// in after this is constructed; resolving it per call is what tolerates that.
+func NewRactorShepherd(acc *Acceptor, reg *queue.Registry, initialRactors, perUnit int, logger *log.Logger) *RactorShepherd {
+	if logger == nil {
+		logger = log.Default()
+	}
+	if perUnit < 1 {
+		perUnit = 1
+	}
+	units := initialRactors / perUnit
+	if units < 1 {
+		units = 1
+	}
+	return &RactorShepherd{acc: acc, reg: reg, logger: logger, perUnit: perUnit, target: units}
+}
+
+// SetWorkers drives the Ractor count toward n.
+func (s *RactorShepherd) SetWorkers(n int) error {
+	if n < 1 {
+		n = 1
+	}
+
+	s.mu.Lock()
+	current := s.target
+	s.target = n
+	s.mu.Unlock()
+
+	switch {
+	case n > current:
+		// Ractor.new happens in Ruby; SET_SLOTS carries the target in Ractors.
+		return s.setSlots(n * s.perUnit)
+
+	case n < current:
+		// Retire from this side. Only idle conns are drained, so nothing in
+		// flight is lost; a surplus that is busy gets drained on a later tick
+		// rather than blocking the control loop behind application work.
+		want := (current - n) * s.perUnit
+		got := s.reg.DrainIdle(want)
+		if got < want {
+			// Partial drains are counted in whole units, so a unit half drained
+			// is still owed and gets finished next tick rather than forgotten.
+			s.mu.Lock()
+			s.target = current - got/s.perUnit
+			n = s.target
+			s.mu.Unlock()
+			s.logger.Printf("control: drained %d of %d ractors, %d still busy",
+				got, want, want-got)
+		}
+		// Keep Ruby's notion of the target in step, so it neither respawns what
+		// we just drained nor refuses to grow later.
+		return s.setSlots(n * s.perUnit)
+	}
+	return nil
+}
+
+func (s *RactorShepherd) setSlots(n int) error {
+	c := s.acc.Shepherd()
+	if c == nil {
+		return ErrNoShepherd
+	}
+	return c.SetWorkers(n)
+}
+
+// WorkerCount is how many units of capacity are live, which is the number of
+// connected Ractors divided by the unit size -- in Ractor mode each Ractor owns
+// exactly one connection.
+//
+// Taken from the registry rather than from Ruby's heartbeat because the
+// registry is where a drained Ractor disappears first. A controller acting on a
+// stale, higher count would keep draining connections it had already retired.
+func (s *RactorShepherd) WorkerCount() int {
+	n := s.reg.Capacity() / s.perUnit
+	// A partially-filled unit still counts: reporting zero while Ractors are
+	// serving would make the controller spawn a unit that already exists.
+	if n == 0 && s.reg.Capacity() > 0 {
+		return 1
+	}
+	return n
+}
+
+// WorkerPIDs is whatever the Ruby process reports, which in Ractor mode is the
+// single process it is.
+//
+// So the memory guard measures the whole process rather than a per-Ractor
+// share. That is the honest answer -- Ractors share one heap, so "this Ractor's
+// RSS" is not a quantity that exists -- but it does mean the guard's projection
+// of what one more unit costs is derived from a process total, and therefore
+// over-estimates the marginal cost of a Ractor.
+func (s *RactorShepherd) WorkerPIDs() []int {
+	c := s.acc.Shepherd()
+	if c == nil {
+		return nil
+	}
+	return c.WorkerPIDs()
+}
+
+// Connected reports whether the Ruby process is attached and recently heard
+// from.
+func (s *RactorShepherd) Connected() bool {
+	c := s.acc.Shepherd()
+	return c != nil && c.Connected()
+}