// Command sse-load is the acceptance load test for GET /api/stream. // // It opens N concurrent SSE clients (120 by default) for a fixed duration, // posts scenario changes on an interval, and measures the end-to-end latency // from the POST to each client receiving the matching scenario event. It also // verifies heartbeat cadence, counts connection drops/reconnects, and writes a // machine-readable JSON summary. // // go run ./scripts/sse-load -base http://127.0.0.1:18080 -duration 5m // // Credentials come from -user/-pass or CONTROL_USER/CONTROL_PASS. The tool // exits non-zero when a client drops, an event is not delivered, or the p95 // scenario latency exceeds 2 s: the contract's acceptance threshold. package main import ( "bufio" "bytes" "context" "encoding/json" "errors" "flag" "fmt" "io" "math" "net/http" "os" "os/signal" "sort" "strings" "sync" "syscall" "time" ) const scenarioThreshold = 2 * time.Second // scenarioBodies rotate so consecutive changes differ in payload as well as // version. var scenarioBodies = []string{ `{"scenario":"sunny-saturday-market","weather":{"temp_delta_c":4,"precip_mm":0},"event":{"type":"market","uplift":0.2}}`, `{"scenario":"rainy-saturday","weather":{"temp_delta_c":-3,"precip_mm":4},"event":{"type":"rain","uplift":-0.15}}`, `{"scenario":"weekday-event","weather":{"temp_delta_c":0,"precip_mm":0},"event":{"type":"event","uplift":0.1}}`, `{"scenario":"base","weather":{"temp_delta_c":0,"precip_mm":0},"event":{"type":"","uplift":0}}`, } type scenarioEvent struct { Version int `json:"version"` At string `json:"at"` } type client struct { id int mu sync.Mutex connected bool receipts map[int]time.Time // scenario version -> first receipt pings []time.Time readyOnce sync.Once } func (c *client) setConnected(connected bool) { c.mu.Lock() c.connected = connected c.mu.Unlock() } func (c *client) isConnected() bool { c.mu.Lock() defer c.mu.Unlock() return c.connected } func (c *client) recordScenario(version int, at time.Time) { c.mu.Lock() if c.receipts == nil { c.receipts = make(map[int]time.Time) } if _, exists := c.receipts[version]; !exists { c.receipts[version] = at } c.mu.Unlock() } func (c *client) recordPing(at time.Time) { c.mu.Lock() c.pings = append(c.pings, at) c.mu.Unlock() } func (c *client) receipt(version int) (time.Time, bool) { c.mu.Lock() defer c.mu.Unlock() at, ok := c.receipts[version] return at, ok } func (c *client) pingCount() int { c.mu.Lock() defer c.mu.Unlock() return len(c.pings) } func (c *client) signalReady(ready chan<- struct{}) { c.readyOnce.Do(func() { select { case ready <- struct{}{}: default: } }) } type changeResult struct { Version int `json:"version"` PostAt time.Time `json:"post_at"` Connected int `json:"connected_at_post"` Received int `json:"received"` Missing int `json:"missing"` LatenciesMS []float64 `json:"-"` P50MS float64 `json:"p50_ms"` P95MS float64 `json:"p95_ms"` P99MS float64 `json:"p99_ms"` MaxMS float64 `json:"max_ms"` } type summary struct { StartedAt time.Time `json:"started_at"` DurationS float64 `json:"duration_s"` BaseURL string `json:"base_url"` Clients int `json:"clients_configured"` PeakConnected int `json:"clients_peak_connected"` ConnectedAfter int `json:"clients_connected_after_warmup"` Drops int `json:"connection_drops"` PostErrors int `json:"scenario_post_errors"` ScenarioChanges int `json:"scenario_changes"` Received int `json:"scenario_events_received"` Missing int `json:"scenario_events_missing"` LatencyCount int `json:"scenario_latency_samples"` LatencyP50MS float64 `json:"scenario_p50_ms"` LatencyP95MS float64 `json:"scenario_p95_ms"` LatencyP99MS float64 `json:"scenario_p99_ms"` LatencyMaxMS float64 `json:"scenario_max_ms"` Changes []changeResult `json:"changes"` Ping pingSummary `json:"heartbeat"` Errors []string `json:"errors"` Passed bool `json:"passed"` FailureReasons []string `json:"failure_reasons,omitempty"` } type pingSummary struct { Unique int `json:"unique_server_timestamps"` MinIntervalMS float64 `json:"min_interval_ms"` MedianIntervalMS float64 `json:"median_interval_ms"` P95IntervalMS float64 `json:"p95_interval_ms"` MaxIntervalMS float64 `json:"max_interval_ms"` PerClientMin int `json:"per_client_min"` PerClientMedian int `json:"per_client_median"` PerClientMax int `json:"per_client_max"` } type recorder struct { mu sync.Mutex clients []*client connected int peak int drops int postErrs int errors []string pingTimes map[time.Time]struct{} } func (r *recorder) connectedNow() int { r.mu.Lock() defer r.mu.Unlock() return r.connected } func (r *recorder) addConnected(delta int) { r.mu.Lock() r.connected += delta if r.connected > r.peak { r.peak = r.connected } r.mu.Unlock() } func (r *recorder) addError(message string, drop bool) { r.mu.Lock() if drop { r.drops++ } else { r.postErrs++ } if len(r.errors) < 40 { r.errors = append(r.errors, message) } r.mu.Unlock() } func (r *recorder) addPing(t time.Time) { r.mu.Lock() if r.pingTimes == nil { r.pingTimes = make(map[time.Time]struct{}) } r.pingTimes[t] = struct{}{} r.mu.Unlock() } func (r *recorder) snapshot() (peak, drops, postErrs int, errs []string, pings []time.Time) { r.mu.Lock() defer r.mu.Unlock() peak, drops, postErrs = r.peak, r.drops, r.postErrs errs = append([]string(nil), r.errors...) pings = make([]time.Time, 0, len(r.pingTimes)) for t := range r.pingTimes { pings = append(pings, t) } sort.Slice(pings, func(i, j int) bool { return pings[i].Before(pings[j]) }) return } func main() { base := flag.String("base", "http://127.0.0.1:18080", "Go API base URL") clientsN := flag.Int("clients", 120, "concurrent SSE clients") duration := flag.Duration("duration", 5*time.Minute, "load-test duration") changeEvery := flag.Duration("changes", 30*time.Second, "interval between scenario POSTs; 0 disables") warmup := flag.Duration("warmup", 10*time.Second, "max time to wait for all clients to connect") user := flag.String("user", os.Getenv("CONTROL_USER"), "basic-auth user for POST /api/scenario") pass := flag.String("pass", os.Getenv("CONTROL_PASS"), "basic-auth password for POST /api/scenario") jsonOut := flag.String("json", "", "write the JSON summary to this path") flag.Parse() if *clientsN < 1 { fatalf("clients must be >= 1") } if *duration <= 0 { fatalf("duration must be > 0") } if *changeEvery > 0 && (*user == "" || *pass == "") { fatalf("POST /api/scenario needs -user/-pass or CONTROL_USER/CONTROL_PASS") } ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() ctx, cancel := context.WithTimeout(ctx, *duration) defer cancel() rec := &recorder{clients: make([]*client, *clientsN), pingTimes: make(map[time.Time]struct{})} ready := make(chan struct{}, *clientsN) started := time.Now() var wg sync.WaitGroup for i := 0; i < *clientsN; i++ { c := &client{id: i} rec.clients[i] = c wg.Add(1) go func() { defer wg.Done() runClient(ctx, *base, c, rec, ready) }() } // Wait until every client has received the initial scenario event. connectedAfter := waitReady(ctx, ready, *clientsN, *warmup) fmt.Printf("clients connected: %d/%d after warmup\n", connectedAfter, *clientsN) if connectedAfter < *clientsN { fmt.Printf("warning: only %d/%d clients connected before warmup deadline\n", connectedAfter, *clientsN) } changes := []changeResult{} if *changeEvery > 0 { changes = runChanges(ctx, *base, *user, *pass, *changeEvery, rec) } <-ctx.Done() cancel() done := make(chan struct{}) go func() { wg.Wait(); close(done) }() select { case <-done: case <-time.After(5 * time.Second): fmt.Println("warning: clients did not stop within 5s") } elapsed := time.Since(started) sum := buildSummary(rec, changes, *base, *clientsN, connectedAfter, started, elapsed) printSummary(sum) if *jsonOut != "" { if err := writeJSON(*jsonOut, sum); err != nil { fatalf("write %s: %v", *jsonOut, err) } fmt.Printf("json written to %s\n", *jsonOut) } if !sum.Passed { os.Exit(1) } } func waitReady(ctx context.Context, ready <-chan struct{}, want int, timeout time.Duration) int { timer := time.NewTimer(timeout) defer timer.Stop() count := 0 for count < want { select { case <-ready: count++ case <-timer.C: return count case <-ctx.Done(): return count } } return count } func runClient(ctx context.Context, base string, c *client, rec *recorder, ready chan<- struct{}) { transport := &http.Transport{ Proxy: nil, DisableCompression: true, MaxIdleConnsPerHost: 1, IdleConnTimeout: 0, } httpClient := &http.Client{Transport: transport} defer transport.CloseIdleConnections() streamURL := strings.TrimRight(base, "/") + "/api/stream" failures := 0 for ctx.Err() == nil { req, err := http.NewRequestWithContext(ctx, http.MethodGet, streamURL, nil) if err != nil { rec.addError(fmt.Sprintf("client %d: build request: %v", c.id, err), true) c.signalReady(ready) return } req.Header.Set("Accept", "text/event-stream") resp, err := httpClient.Do(req) if err != nil { if ctx.Err() != nil { return } failures++ rec.addError(fmt.Sprintf("client %d: connect: %v", c.id, err), true) c.signalReady(ready) sleepRetry(ctx) continue } if resp.StatusCode != http.StatusOK { snippet, _ := io.ReadAll(io.LimitReader(resp.Body, 128)) _ = resp.Body.Close() failures++ rec.addError(fmt.Sprintf("client %d: status %d: %s", c.id, resp.StatusCode, strings.TrimSpace(string(snippet))), true) c.signalReady(ready) sleepRetry(ctx) continue } c.setConnected(true) rec.addConnected(1) readStream(ctx, resp.Body, c, rec, ready) _ = resp.Body.Close() c.setConnected(false) rec.addConnected(-1) if ctx.Err() != nil { return } failures++ rec.addError(fmt.Sprintf("client %d: stream ended unexpectedly", c.id), true) c.signalReady(ready) sleepRetry(ctx) } } // readStream parses one SSE response. It returns when the body ends or the // context is cancelled. func readStream(ctx context.Context, body io.Reader, c *client, rec *recorder, ready chan<- struct{}) { scanner := bufio.NewScanner(body) scanner.Buffer(make([]byte, 0, 64*1024), 1<<20) eventName := "" eventID := "" var data []string for ctx.Err() == nil && scanner.Scan() { line := scanner.Text() if line == "" { now := time.Now() switch eventName { case "scenario": version := 0 var event scenarioEvent if err := json.Unmarshal([]byte(strings.Join(data, "\n")), &event); err == nil { version = event.Version } if version == 0 && eventID != "" { _, _ = fmt.Sscanf(eventID, "%d", &version) } if version > 0 { c.recordScenario(version, now) c.signalReady(ready) } case "ping": c.recordPing(now) var payload struct { T string `json:"t"` } if err := json.Unmarshal([]byte(strings.Join(data, "\n")), &payload); err == nil { if t, err := time.Parse(time.RFC3339, payload.T); err == nil { rec.addPing(t.UTC()) } } } eventName, eventID, data = "", "", nil continue } switch { case strings.HasPrefix(line, "event:"): eventName = strings.TrimSpace(strings.TrimPrefix(line, "event:")) case strings.HasPrefix(line, "id:"): eventID = strings.TrimSpace(strings.TrimPrefix(line, "id:")) case strings.HasPrefix(line, "data:"): data = append(data, strings.TrimPrefix(line, "data:")) } } } func runChanges(ctx context.Context, base, user, pass string, every time.Duration, rec *recorder) []changeResult { client := &http.Client{Timeout: 10 * time.Second} scenarioURL := strings.TrimRight(base, "/") + "/api/scenario" var out []changeResult ticker := time.NewTicker(every) defer ticker.Stop() for i := 0; ; i++ { select { case <-ctx.Done(): return out case <-ticker.C: } body := scenarioBodies[i%len(scenarioBodies)] postAt := time.Now() version, err := postScenario(ctx, client, scenarioURL, user, pass, body) if err != nil { if ctx.Err() != nil { return out } rec.addError("scenario POST: "+err.Error(), false) continue } result := changeResult{ Version: version, PostAt: postAt, Connected: rec.connectedNow(), } // Wait up to 2s for every currently connected client to receive it. deadline := time.Now().Add(2 * time.Second) for { result.Received = 0 for _, c := range rec.clients { if !c.isConnected() { continue } if _, ok := c.receipt(version); ok { result.Received++ } } result.Missing = result.Connected - result.Received if result.Missing <= 0 || time.Now().After(deadline) { break } time.Sleep(10 * time.Millisecond) } for _, c := range rec.clients { if !c.isConnected() { continue } if at, ok := c.receipt(version); ok { result.LatenciesMS = append(result.LatenciesMS, float64(at.Sub(postAt).Microseconds())/1000.0) } } result.P50MS, result.P95MS, result.P99MS, result.MaxMS = percentiles(result.LatenciesMS) out = append(out, result) fmt.Printf("scenario v%d: %d/%d clients p50=%.1fms p95=%.1fms max=%.1fms\n", version, result.Received, result.Connected, result.P50MS, result.P95MS, result.MaxMS) } } func postScenario(ctx context.Context, client *http.Client, url, user, pass, body string) (int, error) { req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewBufferString(body)) if err != nil { return 0, err } req.Header.Set("Content-Type", "application/json") req.SetBasicAuth(user, pass) resp, err := client.Do(req) if err != nil { return 0, err } defer resp.Body.Close() raw, _ := io.ReadAll(io.LimitReader(resp.Body, 4096)) if resp.StatusCode != http.StatusOK { return 0, fmt.Errorf("status %d: %s", resp.StatusCode, strings.TrimSpace(string(raw))) } var parsed struct { Version int `json:"version"` } if err := json.Unmarshal(raw, &parsed); err != nil { return 0, fmt.Errorf("decode response: %w", err) } if parsed.Version <= 0 { return 0, errors.New("response has no version") } return parsed.Version, nil } func buildSummary(rec *recorder, changes []changeResult, base string, clientsN, connectedAfter int, started time.Time, elapsed time.Duration) summary { peak, drops, postErrs, errs, pingTimes := rec.snapshot() sum := summary{ StartedAt: started.UTC(), DurationS: math.Round(elapsed.Seconds()*1000) / 1000, BaseURL: base, Clients: clientsN, PeakConnected: peak, ConnectedAfter: connectedAfter, Drops: drops, PostErrors: postErrs, ScenarioChanges: len(changes), Changes: changes, Errors: errs, } var all []float64 for _, change := range changes { all = append(all, change.LatenciesMS...) sum.Received += change.Received sum.Missing += change.Missing } sum.LatencyCount = len(all) sum.LatencyP50MS, sum.LatencyP95MS, sum.LatencyP99MS, sum.LatencyMaxMS = percentiles(all) sum.Ping = buildPingSummary(pingTimes, rec.clients) // Pass criteria from CONTRACT.md ยง6: 120 clients for 5 minutes, no dropped // connections, p95 scenario latency below 2 s. if peak < clientsN { sum.FailureReasons = append(sum.FailureReasons, fmt.Sprintf("peak connections %d < %d", peak, clientsN)) } if drops > 0 { sum.FailureReasons = append(sum.FailureReasons, fmt.Sprintf("%d dropped/reconnected connections", drops)) } if postErrs > 0 { sum.FailureReasons = append(sum.FailureReasons, fmt.Sprintf("%d scenario POST errors", postErrs)) } if sum.Missing > 0 { sum.FailureReasons = append(sum.FailureReasons, fmt.Sprintf("%d scenario events missing", sum.Missing)) } if len(all) > 0 && sum.LatencyP95MS > scenarioThreshold.Seconds()*1000 { sum.FailureReasons = append(sum.FailureReasons, fmt.Sprintf("scenario p95 %.1fms > 2000ms", sum.LatencyP95MS)) } if sum.Ping.P95IntervalMS > 17_000 { sum.FailureReasons = append(sum.FailureReasons, fmt.Sprintf("heartbeat p95 interval %.0fms > 17000ms", sum.Ping.P95IntervalMS)) } sum.Passed = len(sum.FailureReasons) == 0 return sum } func buildPingSummary(pingTimes []time.Time, clients []*client) pingSummary { out := pingSummary{Unique: len(pingTimes)} if len(pingTimes) > 1 { intervals := make([]float64, 0, len(pingTimes)-1) for i := 1; i < len(pingTimes); i++ { intervals = append(intervals, float64(pingTimes[i].Sub(pingTimes[i-1]).Microseconds())/1000.0) } out.MinIntervalMS = minFloat(intervals) out.MedianIntervalMS = percentile(intervals, 50) out.P95IntervalMS = percentile(intervals, 95) out.MaxIntervalMS = maxFloat(intervals) } counts := make([]int, 0, len(clients)) for _, c := range clients { counts = append(counts, c.pingCount()) } if len(counts) > 0 { sort.Ints(counts) out.PerClientMin = counts[0] out.PerClientMedian = counts[len(counts)/2] out.PerClientMax = counts[len(counts)-1] } return out } func percentiles(values []float64) (p50, p95, p99, max float64) { if len(values) == 0 { return 0, 0, 0, 0 } return percentile(values, 50), percentile(values, 95), percentile(values, 99), maxFloat(values) } // percentile uses the nearest-rank method on a sorted copy. func percentile(values []float64, p float64) float64 { if len(values) == 0 { return 0 } sorted := append([]float64(nil), values...) sort.Float64s(sorted) rank := int(math.Ceil(p/100*float64(len(sorted)))) - 1 if rank < 0 { rank = 0 } if rank >= len(sorted) { rank = len(sorted) - 1 } return math.Round(sorted[rank]*10) / 10 } func minFloat(values []float64) float64 { m := values[0] for _, v := range values[1:] { if v < m { m = v } } return m } func maxFloat(values []float64) float64 { m := values[0] for _, v := range values[1:] { if v > m { m = v } } return m } func sleepRetry(ctx context.Context) { timer := time.NewTimer(3 * time.Second) defer timer.Stop() select { case <-ctx.Done(): case <-timer.C: } } func printSummary(sum summary) { fmt.Println() fmt.Println("=== SSE load test ===") fmt.Printf("duration: %.1fs\n", sum.DurationS) fmt.Printf("clients: %d configured, %d peak connected, %d after warmup\n", sum.Clients, sum.PeakConnected, sum.ConnectedAfter) fmt.Printf("connections: %d drops/reconnects, %d scenario POST errors\n", sum.Drops, sum.PostErrors) fmt.Printf("scenario changes: %d (%d events received, %d missing)\n", sum.ScenarioChanges, sum.Received, sum.Missing) fmt.Printf("scenario latency: p50=%.1fms p95=%.1fms p99=%.1fms max=%.1fms (n=%d)\n", sum.LatencyP50MS, sum.LatencyP95MS, sum.LatencyP99MS, sum.LatencyMaxMS, sum.LatencyCount) fmt.Printf("heartbeat: %d server pings, interval min=%.0fms median=%.0fms p95=%.0fms max=%.0fms\n", sum.Ping.Unique, sum.Ping.MinIntervalMS, sum.Ping.MedianIntervalMS, sum.Ping.P95IntervalMS, sum.Ping.MaxIntervalMS) fmt.Printf("heartbeat/client: min=%d median=%d max=%d\n", sum.Ping.PerClientMin, sum.Ping.PerClientMedian, sum.Ping.PerClientMax) if len(sum.Errors) > 0 { fmt.Println("errors:") for _, err := range sum.Errors { fmt.Printf(" - %s\n", err) } } if sum.Passed { fmt.Println("result: PASS") } else { fmt.Println("result: FAIL") for _, reason := range sum.FailureReasons { fmt.Printf(" - %s\n", reason) } } } func writeJSON(path string, sum summary) error { raw, err := json.MarshalIndent(sum, "", " ") if err != nil { return err } raw = append(raw, '\n') return os.WriteFile(path, raw, 0o644) } func fatalf(format string, args ...any) { fmt.Fprintf(os.Stderr, "sse-load: "+format+"\n", args...) os.Exit(2) }