Add auto (record-on-miss) mode and multi-instance support

auto mode: serves from cassette on match, forwards + records on miss.
Cassette path is optional in all modes — defaults to <target-host>.json.

Multi-instance: set BUFFR_0_TARGET, BUFFR_1_TARGET, … to run multiple
proxies in a single process, each on its own port with its own cassette.
Useful for containerized setups where the app points at multiple APIs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: robin-bially

cmd/buffr/main.go

@@ -44,11 +44,19 @@ func main() {
 		usage()
 		os.Exit(2)
 	}
+	// Multi-instance mode: BUFFR_0_TARGET (and optionally BUFFR_1_TARGET, …)
+	// takes precedence over any subcommand.
+	if instances := loadInstances(); len(instances) > 0 {
+		os.Exit(runInstances(instances))
+	}
+
 	switch args[0] {
 	case "record":
 		os.Exit(runRecord(args[1:]))
 	case "replay":
 		os.Exit(runReplay(args[1:]))
+	case "auto":
+		os.Exit(runAuto(args[1:]))
 	case "-h", "--help", "help":
 		usage()
 		os.Exit(0)
@@ -63,19 +71,25 @@ func usage() {
 	fmt.Fprintln(os.Stderr, `buffr — record/replay HTTP + WebSocket proxy
 
 Usage:
-  buffr record  --target <url> --port <p> --cassette <file>
-  buffr replay  --cassette <file> --port <p>
+  buffr record  --target <url> [--port <p>] [--cassette <file>]
+  buffr replay  [--cassette <file>] [--port <p>]
+  buffr auto    --target <url> [--port <p>] [--cassette <file>]
 
 Environment variables (flags take precedence):
-  BUFFR_MODE      subcommand (record|replay) — used when no CLI argument is given
-  BUFFR_TARGET    upstream URL for record mode
+  BUFFR_MODE      subcommand (record|replay|auto) — used when no CLI argument is given
+  BUFFR_TARGET    upstream URL for record/auto mode
   BUFFR_PORT      local port (default 8080)
-  BUFFR_CASSETTE  cassette file path
+  BUFFR_CASSETTE  cassette file path (auto-generated from target host if omitted)
+
+Multi-instance (one process, many ports):
+  BUFFR_0_TARGET=https://api.openai.com   BUFFR_0_PORT=8081
+  BUFFR_1_TARGET=https://api.anthropic.com BUFFR_1_PORT=8082
+  …  (BUFFR_N_CASSETTE and BUFFR_N_MODE are optional per instance)
 
 Examples:
-  buffr record --target https://api.openai.com --port 8080 --cassette session.json
+  buffr auto --target https://api.openai.com --port 8080
   buffr replay --cassette session.json --port 8080
-  BUFFR_MODE=replay BUFFR_CASSETTE=/data/session.json buffr`)
+  BUFFR_MODE=auto BUFFR_TARGET=https://api.openai.com buffr`)
 }
 
 // envStr returns the value of the environment variable key, or fallback if unset.
@@ -103,22 +117,23 @@ func runRecord(args []string) int {
 	port := fs.Int("port", envInt("BUFFR_PORT", 8080), "local port to listen on [BUFFR_PORT]")
 	cass := fs.String("cassette", envStr("BUFFR_CASSETTE", ""), "cassette file to write (required) [BUFFR_CASSETTE]")
 	_ = fs.Parse(args)
-	if *target == "" || *cass == "" {
-		fmt.Fprintln(os.Stderr, "record: --target and --cassette are required")
+	if *target == "" {
+		fmt.Fprintln(os.Stderr, "record: --target is required")
 		return 2
 	}
 	u, err := url.Parse(*target)
 	if err != nil || u.Scheme == "" || u.Host == "" {
 		fmt.Fprintf(os.Stderr, "record: invalid --target %q\n", *target)
 		return 2
 	}
-	rec := proxy.NewRecorder(*cass)
+	cassPath := cassettePath(*cass, u.Host)
+	rec := proxy.NewRecorder(cassPath)
 	mux := http.NewServeMux()
 	mux.Handle("/", routeUpgrade(
 		proxy.RecordWSHandler(u, rec),
 		proxy.RecordHandler(u, rec),
 	))
-	return serve(*port, mux, "record", *cass)
+	return serve(*port, mux, "record", cassPath)
 }
 
 func runReplay(args []string) int {
@@ -159,6 +174,139 @@ func routeUpgrade(wsHandler, httpHandler http.Handler) http.Handler {
 	})
 }
 
+// cassettePath returns path if non-empty, otherwise derives a filename from
+// the target host (e.g. "api.openai.com.json") in the current directory.
+func cassettePath(path, targetHost string) string {
+	if path != "" {
+		return path
+	}
+	return targetHost + ".json"
+}
+
+func runAuto(args []string) int {
+	fs := flag.NewFlagSet("auto", flag.ExitOnError)
+	target := fs.String("target", envStr("BUFFR_TARGET", ""), "upstream URL to proxy to (required) [BUFFR_TARGET]")
+	port := fs.Int("port", envInt("BUFFR_PORT", 8080), "local port to listen on [BUFFR_PORT]")
+	cass := fs.String("cassette", envStr("BUFFR_CASSETTE", ""), "cassette file (auto-generated if omitted) [BUFFR_CASSETTE]")
+	_ = fs.Parse(args)
+	if *target == "" {
+		fmt.Fprintln(os.Stderr, "auto: --target is required")
+		return 2
+	}
+	u, err := url.Parse(*target)
+	if err != nil || u.Scheme == "" || u.Host == "" {
+		fmt.Fprintf(os.Stderr, "auto: invalid --target %q\n", *target)
+		return 2
+	}
+	cassPath := cassettePath(*cass, u.Host)
+	rec, existing := proxy.NewAutoRecorder(cassPath)
+	m := matcher.New(existing, matcher.JSONBodyNormalizer)
+	rep := proxy.NewWSReplayer(existing)
+	mux := http.NewServeMux()
+	mux.Handle("/", routeUpgrade(
+		proxy.AutoWSHandler(u, rec, rep),
+		proxy.AutoHandler(u, rec, m),
+	))
+	return serve(*port, mux, "auto", cassPath)
+}
+
+// instanceConfig holds the parsed configuration for one proxy instance.
+type instanceConfig struct {
+	mode     string
+	target   *url.URL
+	port     int
+	cassette string
+}
+
+// loadInstances reads BUFFR_0_TARGET, BUFFR_1_TARGET, … from the environment
+// and returns one instanceConfig per indexed group found. Returns nil when no
+// indexed variables are set, signalling single-instance mode.
+func loadInstances() []instanceConfig {
+	var out []instanceConfig
+	for i := 0; ; i++ {
+		pfx := fmt.Sprintf("BUFFR_%d_", i)
+		rawTarget := os.Getenv(pfx + "TARGET")
+		if rawTarget == "" {
+			break
+		}
+		u, err := url.Parse(rawTarget)
+		if err != nil || u.Scheme == "" || u.Host == "" {
+			fmt.Fprintf(os.Stderr, "buffr: invalid %sTARGET=%q, skipping\n", pfx, rawTarget)
+			continue
+		}
+		mode := os.Getenv(pfx + "MODE")
+		if mode == "" {
+			mode = "auto"
+		}
+		port := envInt(pfx+"PORT", 8080+i)
+		cass := cassettePath(os.Getenv(pfx+"CASSETTE"), u.Host)
+		out = append(out, instanceConfig{mode: mode, target: u, port: port, cassette: cass})
+	}
+	return out
+}
+
+// runInstances starts one HTTP server per instanceConfig in separate goroutines
+// and blocks until SIGINT/SIGTERM, then shuts them all down gracefully.
+func runInstances(instances []instanceConfig) int {
+	var servers []*http.Server
+	for _, cfg := range instances {
+		cfg := cfg
+		var mux *http.ServeMux
+		switch cfg.mode {
+		case "record":
+			rec := proxy.NewRecorder(cfg.cassette)
+			mux = http.NewServeMux()
+			mux.Handle("/", routeUpgrade(
+				proxy.RecordWSHandler(cfg.target, rec),
+				proxy.RecordHandler(cfg.target, rec),
+			))
+		case "replay":
+			c, err := cassette.Load(cfg.cassette)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "buffr: failed to load cassette %s: %v\n", cfg.cassette, err)
+				return 1
+			}
+			m := matcher.New(c, matcher.JSONBodyNormalizer)
+			rep := proxy.NewWSReplayer(c)
+			mux = http.NewServeMux()
+			mux.Handle("/", routeUpgrade(
+				proxy.ReplayWSHandler(rep),
+				proxy.ReplayHandler(m),
+			))
+		default: // "auto"
+			rec, existing := proxy.NewAutoRecorder(cfg.cassette)
+			m := matcher.New(existing, matcher.JSONBodyNormalizer)
+			rep := proxy.NewWSReplayer(existing)
+			mux = http.NewServeMux()
+			mux.Handle("/", routeUpgrade(
+				proxy.AutoWSHandler(cfg.target, rec, rep),
+				proxy.AutoHandler(cfg.target, rec, m),
+			))
+		}
+		addr := fmt.Sprintf(":%d", cfg.port)
+		srv := &http.Server{Addr: addr, Handler: mux}
+		servers = append(servers, srv)
+		go func() {
+			fmt.Fprintf(os.Stderr, "buffr %s on %s → target=%s cassette=%s\n",
+				cfg.mode, addr, cfg.target, cfg.cassette)
+			if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+				fmt.Fprintf(os.Stderr, "buffr: server error on %s: %v\n", addr, err)
+			}
+		}()
+	}
+
+	stop := make(chan os.Signal, 1)
+	signal.Notify(stop, syscall.SIGINT, syscall.SIGTERM)
+	<-stop
+	fmt.Fprintln(os.Stderr, "buffr: shutting down…")
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	for _, srv := range servers {
+		_ = srv.Shutdown(ctx)
+	}
+	return 0
+}
+
 func serve(port int, h http.Handler, mode, cass string) int {
 	addr := fmt.Sprintf(":%d", port)
 	srv := &http.Server{Addr: addr, Handler: h}

internal/proxy/http.go

@@ -42,6 +42,67 @@ func (r *Recorder) Append(it cassette.Interaction) error {
 	return cassette.Save(r.path, r.cassette)
 }
 
+// NewAutoRecorder creates a Recorder pre-seeded from an existing cassette file.
+// If the file does not exist yet, an empty cassette is used. The returned
+// cassette snapshot can be handed to matcher.New so the auto handler can
+// match against already-recorded interactions.
+func NewAutoRecorder(path string) (*Recorder, *cassette.Cassette) {
+	c, err := cassette.Load(path)
+	if err != nil {
+		c = &cassette.Cassette{Version: cassette.CurrentVersion}
+	}
+	return &Recorder{cassette: c, path: path}, c
+}
+
+// AutoHandler is the record-on-miss handler: it serves from the cassette when
+// a match exists, and falls back to forwarding + recording when it does not.
+// This lets tests run fully offline once every interaction has been captured,
+// while still accumulating new cassette entries transparently on first run.
+func AutoHandler(target *url.URL, rec *Recorder, m *matcher.Matcher) http.Handler {
+	record := RecordHandler(target, rec)
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, err := io.ReadAll(r.Body)
+		if err != nil {
+			http.Error(w, "buffr: failed to read request body: "+err.Error(), http.StatusInternalServerError)
+			return
+		}
+		r.Body.Close()
+
+		ex := m.Take(r.Method, r.URL.Path, string(body))
+		if ex == nil {
+			// Cache miss — forward to upstream and record.
+			r.Body = io.NopCloser(bytes.NewReader(body))
+			record.ServeHTTP(w, r)
+			return
+		}
+
+		// Cache hit — replay from cassette.
+		for k, vs := range ex.Response.Headers {
+			for _, v := range vs {
+				w.Header().Add(k, v)
+			}
+		}
+		w.WriteHeader(ex.Response.Status)
+		flusher, _ := w.(http.Flusher)
+
+		if len(ex.Response.BodyChunks) > 0 {
+			for _, c := range ex.Response.BodyChunks {
+				if c.DelayMs > 0 {
+					time.Sleep(time.Duration(c.DelayMs) * time.Millisecond)
+				}
+				if _, werr := w.Write([]byte(c.Data)); werr != nil {
+					return
+				}
+				if flusher != nil {
+					flusher.Flush()
+				}
+			}
+			return
+		}
+		_, _ = w.Write([]byte(ex.Response.Body))
+	})
+}
+
 // RecordHandler returns an http.Handler that proxies every request to `target`
 // and writes the round-trip to the recorder. It supports `text/event-stream`
 // responses by streaming chunks through and capturing each chunk with the

internal/proxy/websocket.go

@@ -27,6 +27,20 @@ var upgrader = websocket.Upgrader{
 	HandshakeTimeout: 30 * time.Second,
 }
 
+// AutoWSHandler replays the next recorded WebSocket session when one is
+// available, and falls back to forwarding + recording when the cassette is
+// exhausted. Matches the record-on-miss semantics of AutoHandler.
+func AutoWSHandler(target *url.URL, rec *Recorder, rep *wsReplayer) http.Handler {
+	record := RecordWSHandler(target, rec)
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if rep.Remaining() > 0 {
+			ReplayWSHandler(rep).ServeHTTP(w, r)
+			return
+		}
+		record.ServeHTTP(w, r)
+	})
+}
+
 // RecordWSHandler proxies WebSocket connections to the upstream target and
 // records every frame in both directions to the recorder.
 //