puma-plus-core 0.1.0

data/go/internal/frontend/launcher_test.go

@@ -0,0 +1,289 @@
+package frontend_test
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The launcher is Ruby, so it is tested by running it, the same way the wire
+// codec's Ruby half is. --dry-run makes that cheap: it resolves everything and
+// prints the exec line instead of performing it, so translation and precedence
+// can be asserted without booting a server.
+
+type launchEnv struct {
+	dir  string
+	root string
+	ruby string
+}
+
+func setupLauncher(t *testing.T) launchEnv {
+	t.Helper()
+
+	ruby, err := exec.LookPath("ruby")
+	if err != nil {
+		t.Skipf("ruby not on PATH: %v", err)
+	}
+	root, err := filepath.Abs("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dir := t.TempDir()
+	write(t, filepath.Join(dir, "config.ru"),
+		"run ->(env) { [200, {\"content-type\"=>\"text/plain\"}, [\"ok\\n\"]] }\n")
+	return launchEnv{dir: dir, root: root, ruby: ruby}
+}
+
+func write(t *testing.T, path, body string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// plan runs the launcher with --dry-run and returns its stdout plus stderr.
+func (e launchEnv) plan(t *testing.T, args ...string) (string, string) {
+	t.Helper()
+	full := append([]string{
+		"-I", filepath.Join(e.root, "gem", "lib"),
+		filepath.Join(e.root, "gem", "exe", "puma-plus"),
+		"--dry-run",
+	}, args...)
+
+	cmd := exec.Command(e.ruby, full...)
+	cmd.Dir = e.dir
+	// A path that exists so the "cannot find the server binary" check passes;
+	// --dry-run never runs it.
+	cmd.Env = append(os.Environ(), "PUMA_PLUS_BINARY="+e.ruby)
+	var out, errb strings.Builder
+	cmd.Stdout, cmd.Stderr = &out, &errb
+	if err := cmd.Run(); err != nil {
+		t.Fatalf("launcher failed: %v\nstdout:\n%s\nstderr:\n%s", err, out.String(), errb.String())
+	}
+	return out.String(), errb.String()
+}
+
+func execLine(t *testing.T, plan string) string {
+	t.Helper()
+	for _, l := range strings.Split(plan, "\n") {
+		if strings.HasPrefix(l, "exec:") {
+			return l
+		}
+	}
+	t.Fatalf("no exec line in plan:\n%s", plan)
+	return ""
+}
+
+// TestLauncherTranslatesConfigFile: the DSL is the human interface and the Go
+// flags are the machine one, so the mapping between them is the thing that can
+// silently rot.
+func TestLauncherTranslatesConfigFile(t *testing.T) {
+	e := setupLauncher(t)
+	write(t, filepath.Join(e.dir, "config", "puma-plus.rb"), `
+port 4321
+threads 7
+workers 3
+environment "production"
+autoscale min: 2, max: 9, target_queue_p95: "40ms"
+activate_control_app "tcp://127.0.0.1:4322"
+`)
+
+	out, _ := e.plan(t)
+	line := execLine(t, out)
+
+	for _, want := range []string{
+		"-listen 0.0.0.0:4321", "-threads 7", "-workers 3",
+		"-autoscale", "-min-workers 2", "-max-workers 9",
+		"-target-queue-p95 40ms", "-control 127.0.0.1:4322",
+	} {
+		if !strings.Contains(line, want) {
+			t.Errorf("exec line missing %q\ngot: %s", want, line)
+		}
+	}
+}
+
+// TestLauncherCLIBeatsConfigFile is puma's precedence, and the reason the three
+// option layers are kept separate rather than merged on read.
+func TestLauncherCLIBeatsConfigFile(t *testing.T) {
+	e := setupLauncher(t)
+	write(t, filepath.Join(e.dir, "config", "puma-plus.rb"), "port 4321\nworkers 3\n")
+
+	out, _ := e.plan(t, "--port", "9999", "--workers", "1")
+	line := execLine(t, out)
+
+	if !strings.Contains(line, "-listen 0.0.0.0:9999") || !strings.Contains(line, "-workers 1") {
+		t.Errorf("command line did not override the config file\ngot: %s", line)
+	}
+	if strings.Contains(line, "4321") || strings.Contains(line, "-workers 3") {
+		t.Errorf("config-file values survived a command-line override\ngot: %s", line)
+	}
+}
+
+// TestLauncherEnvironmentSelectsConfigFile: config/puma-plus/<env>.rb wins over
+// config/puma-plus.rb, as puma does. Getting this backwards would silently boot
+// production with development settings.
+func TestLauncherEnvironmentSelectsConfigFile(t *testing.T) {
+	e := setupLauncher(t)
+	write(t, filepath.Join(e.dir, "config", "puma-plus.rb"), "port 1111\n")
+	write(t, filepath.Join(e.dir, "config", "puma-plus", "production.rb"), "port 2222\n")
+
+	out, _ := e.plan(t, "-e", "production")
+	if line := execLine(t, out); !strings.Contains(line, "-listen 0.0.0.0:2222") {
+		t.Errorf("environment-specific config was not preferred\ngot: %s", line)
+	}
+
+	out, _ = e.plan(t)
+	if line := execLine(t, out); !strings.Contains(line, "-listen 0.0.0.0:1111") {
+		t.Errorf("plain config should be used when no env file matches\ngot: %s", line)
+	}
+}
+
+// TestLauncherAcceptsPortedPumaConfig: a config carried over from puma should
+// boot and then say what it dropped, rather than failing on the first line that
+// has no equivalent.
+func TestLauncherAcceptsPortedPumaConfig(t *testing.T) {
+	e := setupLauncher(t)
+	write(t, filepath.Join(e.dir, "config", "puma-plus.rb"), `
+workers 2
+threads 5, 16
+preload_app!
+prune_bundler
+queue_requests true
+`)
+
+	out, stderr := e.plan(t)
+
+	if !strings.Contains(stderr, "preload_app!") || !strings.Contains(stderr, "prune_bundler") {
+		t.Errorf("ignored puma options should be reported, got stderr:\n%s", stderr)
+	}
+	// A thread range collapses to the max, and says so rather than picking quietly.
+	if !strings.Contains(stderr, "threads 5,16") {
+		t.Errorf("thread range should warn which number was used, got:\n%s", stderr)
+	}
+	if line := execLine(t, out); !strings.Contains(line, "-threads 16") {
+		t.Errorf("thread range should resolve to the max\ngot: %s", line)
+	}
+}
+
+// TestLauncherRejectsBadConfig covers the failures a person hits while editing a
+// config, which must be a sentence rather than a Ruby backtrace.
+func TestLauncherRejectsBadConfig(t *testing.T) {
+	e := setupLauncher(t)
+
+	cases := []struct{ name, config, args, want string }{
+		{"ractors with workers", "ractors 4\nworkers 2\n", "", "one process"},
+		{"min above max", "autoscale min: 9, max: 2\n", "", "min_workers"},
+		{"bad duration", `autoscale target_queue_p95: "soon"` + "\n", "", "not a duration"},
+		{"unix bind", `bind "unix:///tmp/x.sock"` + "\n", "", "unix sockets are not supported"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			write(t, filepath.Join(e.dir, "config", "puma-plus.rb"), tc.config)
+
+			args := []string{
+				"-I", filepath.Join(e.root, "gem", "lib"),
+				filepath.Join(e.root, "gem", "exe", "puma-plus"), "--dry-run",
+			}
+			cmd := exec.Command(e.ruby, args...)
+			cmd.Dir = e.dir
+			cmd.Env = append(os.Environ(), "PUMA_PLUS_BINARY="+e.ruby)
+			out, _ := cmd.CombinedOutput()
+
+			if cmd.ProcessState.ExitCode() == 0 {
+				t.Fatalf("expected a non-zero exit, got success:\n%s", out)
+			}
+			if !strings.Contains(string(out), tc.want) {
+				t.Errorf("error should mention %q, got:\n%s", tc.want, out)
+			}
+			if strings.Contains(string(out), "backtrace") || strings.Contains(string(out), ".rb:in ") {
+				t.Errorf("config error surfaced as a Ruby backtrace:\n%s", out)
+			}
+		})
+	}
+}
+
+// TestLauncherTranslatesTLS covers both spellings of "here is my certificate",
+// since bind-with-query and ssl_bind reach the same place and could drift.
+func TestLauncherTranslatesTLS(t *testing.T) {
+	e := setupLauncher(t)
+	cert := filepath.Join(e.dir, "cert.pem")
+	key := filepath.Join(e.dir, "key.pem")
+	write(t, cert, "-----BEGIN CERTIFICATE-----\n")
+	write(t, key, "-----BEGIN EC PRIVATE KEY-----\n")
+
+	forms := map[string]string{
+		"ssl_bind":   "ssl_bind \"0.0.0.0\", 9443, cert: \"" + cert + "\", key: \"" + key + "\"\n",
+		"bind query": "bind \"ssl://0.0.0.0:9443?cert=" + cert + "&key=" + key + "\"\n",
+		"tls_cert":   "bind \"ssl://0.0.0.0:9443\"\ntls_cert \"" + cert + "\", \"" + key + "\"\n",
+	}
+
+	for name, body := range forms {
+		t.Run(name, func(t *testing.T) {
+			write(t, filepath.Join(e.dir, "config", "puma-plus.rb"), body)
+			line := execLine(t, mustPlan(t, e))
+
+			for _, want := range []string{
+				"-listen-tls 0.0.0.0:9443", "-tls-cert " + cert, "-tls-key " + key,
+			} {
+				if !strings.Contains(line, want) {
+					t.Errorf("exec line missing %q\ngot: %s", want, line)
+				}
+			}
+		})
+	}
+}
+
+// TestLauncherRejectsBadTLS: an unreadable path is a typo in a config file, and
+// should be reported by the thing that read the file rather than surfacing as a
+// server that will not boot.
+func TestLauncherRejectsBadTLS(t *testing.T) {
+	e := setupLauncher(t)
+	cert := filepath.Join(e.dir, "cert.pem")
+	write(t, cert, "-----BEGIN CERTIFICATE-----\n")
+
+	cases := []struct{ name, config, want string }{
+		{
+			"cert without key",
+			"bind \"ssl://0.0.0.0:9443?cert=" + cert + "\"\n",
+			"together",
+		},
+		{
+			"missing file",
+			"ssl_bind \"0.0.0.0\", 9443, cert: \"/nope/cert.pem\", key: \"/nope/key.pem\"\n",
+			"no such file",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			write(t, filepath.Join(e.dir, "config", "puma-plus.rb"), tc.config)
+
+			cmd := exec.Command(e.ruby,
+				"-I", filepath.Join(e.root, "gem", "lib"),
+				filepath.Join(e.root, "gem", "exe", "puma-plus"), "--dry-run")
+			cmd.Dir = e.dir
+			cmd.Env = append(os.Environ(), "PUMA_PLUS_BINARY="+e.ruby)
+			out, _ := cmd.CombinedOutput()
+
+			if cmd.ProcessState.ExitCode() == 0 {
+				t.Fatalf("expected failure, got success:\n%s", out)
+			}
+			if !strings.Contains(string(out), tc.want) {
+				t.Errorf("error should mention %q, got:\n%s", tc.want, out)
+			}
+		})
+	}
+}
+
+func mustPlan(t *testing.T, e launchEnv) string {
+	t.Helper()
+	out, _ := e.plan(t)
+	return out
+}

data/go/internal/frontend/listeners.go

@@ -0,0 +1,196 @@
+package frontend
+
+import (
+	"context"
+	"crypto/tls"
+	"fmt"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/quic-go/quic-go"
+	"github.com/quic-go/quic-go/http3"
+	"golang.org/x/net/http2"
+	"golang.org/x/net/http2/h2c"
+
+	wt "github.com/quic-go/webtransport-go"
+)
+
+// ALPN identifiers.
+const (
+	ALPNHTTP1 = "http/1.1"
+	ALPNHTTP2 = "h2"
+)
+
+// Listeners holds every protocol frontend, all serving the same handler.
+//
+// This is where the protocol-agnostic claim gets tested. An h1 request, an h2
+// stream and an h3 stream arrive through three completely different transports
+// and three different protocol state machines, but all three reduce to the same
+// *http.Request, which the handler turns into the same REQUEST frame. Ruby never
+// learns which one it was, except for the http_version byte it reports back as
+// SERVER_PROTOCOL.
+type Listeners struct {
+	h1   *http.Server
+	tlsS *http.Server
+	h3   *http3.Server
+	wt   *wt.Server
+	log  *log.Logger
+}
+
+// ListenerOptions configures which frontends to start.
+type ListenerOptions struct {
+	Handler http.Handler
+	Logger  *log.Logger
+
+	// Addr is the cleartext HTTP/1.1 address. Empty disables it.
+	Addr string
+	// H2C enables cleartext HTTP/2 on Addr alongside HTTP/1.1.
+	//
+	// Worth having despite being rare in browsers: it isolates HTTP/2's framing
+	// and multiplexing costs from TLS handshake costs, which a TLS-only h2
+	// comparison confounds.
+	H2C bool
+
+	// TLSAddr serves h2 and h1 over TLS via ALPN. Empty disables it.
+	TLSAddr string
+	// H3Addr serves HTTP/3 over QUIC (UDP). Empty disables it.
+	H3Addr string
+
+	// WebTransport, if set, receives the HTTP/3 server so it can accept
+	// Extended CONNECT sessions on the same listener. WebTransport requires h3
+	// -- there is no HTTP/1.1 fallback, because it is built on QUIC streams.
+	WebTransport *wt.Server
+
+	Cert tls.Certificate
+}
+
+// Start brings up every configured frontend.
+func Start(opts ListenerOptions) (*Listeners, error) {
+	if opts.Logger == nil {
+		opts.Logger = log.Default()
+	}
+	l := &Listeners{log: opts.Logger}
+
+	if opts.Addr != "" {
+		h := opts.Handler
+		if opts.H2C {
+			// h2c upgrades a cleartext connection to HTTP/2 without ALPN, so one
+			// port serves both. Requests arrive as ordinary *http.Request with
+			// ProtoMajor 2.
+			h = h2c.NewHandler(opts.Handler, &http2.Server{})
+		}
+		l.h1 = &http.Server{
+			Addr:    opts.Addr,
+			Handler: h,
+			// No Read/WriteTimeout: streaming responses and long polls must
+			// survive. ReadHeaderTimeout alone bounds slowloris without capping
+			// a legitimate long response.
+			ReadHeaderTimeout: 10 * time.Second,
+		}
+		go func() {
+			if err := l.h1.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+				opts.Logger.Printf("http listener: %v", err)
+			}
+		}()
+	}
+
+	// Advertise h3 from the TLS listener, and from h3 itself so a client already
+	// using it refreshes the entry before ma expires.
+	//
+	// Never from the cleartext listener. Its origin is http://, so the h3
+	// advertisement would be cross-origin and browsers ignore it -- and a client
+	// is right to distrust an unauthenticated connection telling it where to go
+	// next.
+	altSvc := ""
+	if opts.H3Addr != "" {
+		v, err := AltSvcHeader(opts.H3Addr)
+		if err != nil {
+			return nil, err
+		}
+		altSvc = v
+	}
+
+	if opts.TLSAddr != "" {
+		tlsHandler := opts.Handler
+		if altSvc != "" {
+			tlsHandler = withAltSvc(tlsHandler, altSvc)
+		}
+		srv := &http.Server{
+			Addr:              opts.TLSAddr,
+			Handler:           tlsHandler,
+			ReadHeaderTimeout: 10 * time.Second,
+			// Advertise h2 first so a capable client negotiates it. Without this
+			// the connection quietly falls back to http/1.1 and an "h2"
+			// benchmark measures h1.
+			TLSConfig: TLSConfig(opts.Cert, ALPNHTTP2, ALPNHTTP1),
+		}
+		if err := http2.ConfigureServer(srv, &http2.Server{}); err != nil {
+			return nil, fmt.Errorf("configuring h2: %w", err)
+		}
+		l.tlsS = srv
+		go func() {
+			if err := srv.ListenAndServeTLS("", ""); err != nil && err != http.ErrServerClosed {
+				opts.Logger.Printf("https listener: %v", err)
+			}
+		}()
+	}
+
+	if opts.H3Addr != "" {
+		// QUIC always runs TLS, so h3 needs the certificate unconditionally.
+		l.h3 = &http3.Server{
+			Addr:      opts.H3Addr,
+			Handler:   withAltSvc(opts.Handler, altSvc),
+			TLSConfig: TLSConfig(opts.Cert, http3.NextProtoH3),
+			QUICConfig: &quic.Config{
+				MaxIdleTimeout: 60 * time.Second,
+				// Streams are requests here, so this is the h3 analogue of a
+				// connection limit -- and the natural place to apply backpressure
+				// to a client rather than queueing its work.
+				MaxIncomingStreams: 1000,
+				// Both required by WebTransport, and harmless without it.
+				// EnableDatagrams is what makes the unreliable channel exist at
+				// all; without it a session negotiates but SendDatagram fails.
+				EnableDatagrams: true,
+				// WebTransport multiplexes its streams inside QUIC streams and
+				// needs to see the bytes that preceded a reset.
+				EnableStreamResetPartialDelivery: true,
+			},
+		}
+		if opts.WebTransport != nil {
+			// webtransport.Server drives the h3 server itself, so that Extended
+			// CONNECT requests are intercepted before ordinary routing. Serving
+			// the h3 server separately as well would bind the port twice.
+			opts.WebTransport.H3 = l.h3
+			l.wt = opts.WebTransport
+			go func() {
+				if err := opts.WebTransport.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+					opts.Logger.Printf("webtransport listener: %v", err)
+				}
+			}()
+		} else {
+			go func() {
+				if err := l.h3.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+					opts.Logger.Printf("h3 listener: %v", err)
+				}
+			}()
+		}
+	}
+
+	return l, nil
+}
+
+// Shutdown stops every frontend.
+func (l *Listeners) Shutdown(ctx context.Context) {
+	if l.h1 != nil {
+		_ = l.h1.Shutdown(ctx)
+	}
+	if l.tlsS != nil {
+		_ = l.tlsS.Shutdown(ctx)
+	}
+	if l.wt != nil {
+		_ = l.wt.Close()
+	} else if l.h3 != nil {
+		_ = l.h3.Close()
+	}
+}