feat: record stream interruption reasons via StreamStatus

- Add StreamStatus type (relay/common) to track stream end reason (done/timeout/client_gone/scanner_error/eof/panic/ping_fail) and accumulate soft errors during streaming via sync.Once + sync.Mutex. - Add StreamResult (relay/helper) as the callback interface: adapters call sr.Error() for soft errors, sr.Stop() for fatal, sr.Done() for normal completion. No early-return problem — multiple errors per chunk are naturally supported. - Refactor StreamScannerHandler callback from func(string) bool to func(string, *StreamResult). All 9 channel adapters updated. - Write stream_status into log other JSON field (admin-only) with status ok/error, end_reason, error_count, and error messages. - Frontend: display stream status in log detail expansion for admins.
2026-03-31 16:50:24 +08:00
parent 5402bf417d
commit 5238f279db
20 changed files with 764 additions and 163 deletions
@@ -162,6 +162,8 @@ type RelayInfo struct {
 	// 若为空，调用 GetFinalRequestRelayFormat 会回退到 RequestConversionChain 的最后一项或 RelayFormat。
 	FinalRequestRelayFormat types.RelayFormat

+	StreamStatus *StreamStatus
+
 	ThinkingContentInfo
 	TokenCountMeta
 	*ClaudeConvertInfo
@@ -0,0 +1,112 @@
+package common
+
+import (
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+)
+
+type StreamEndReason string
+
+const (
+	StreamEndReasonNone        StreamEndReason = ""
+	StreamEndReasonDone        StreamEndReason = "done"
+	StreamEndReasonTimeout     StreamEndReason = "timeout"
+	StreamEndReasonClientGone  StreamEndReason = "client_gone"
+	StreamEndReasonScannerErr  StreamEndReason = "scanner_error"
+	StreamEndReasonHandlerStop StreamEndReason = "handler_stop"
+	StreamEndReasonEOF         StreamEndReason = "eof"
+	StreamEndReasonPanic       StreamEndReason = "panic"
+	StreamEndReasonPingFail    StreamEndReason = "ping_fail"
+)
+
+const maxStreamErrorEntries = 20
+
+type StreamErrorEntry struct {
+	Message   string
+	Timestamp time.Time
+}
+
+type StreamStatus struct {
+	EndReason  StreamEndReason
+	EndError   error
+	endOnce    sync.Once
+
+	mu         sync.Mutex
+	Errors     []StreamErrorEntry
+	ErrorCount int
+}
+
+func NewStreamStatus() *StreamStatus {
+	return &StreamStatus{}
+}
+
+func (s *StreamStatus) SetEndReason(reason StreamEndReason, err error) {
+	if s == nil {
+		return
+	}
+	s.endOnce.Do(func() {
+		s.EndReason = reason
+		s.EndError = err
+	})
+}
+
+func (s *StreamStatus) RecordError(msg string) {
+	if s == nil {
+		return
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.ErrorCount++
+	if len(s.Errors) < maxStreamErrorEntries {
+		s.Errors = append(s.Errors, StreamErrorEntry{
+			Message:   msg,
+			Timestamp: time.Now(),
+		})
+	}
+}
+
+func (s *StreamStatus) HasErrors() bool {
+	if s == nil {
+		return false
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.ErrorCount > 0
+}
+
+func (s *StreamStatus) TotalErrorCount() int {
+	if s == nil {
+		return 0
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.ErrorCount
+}
+
+func (s *StreamStatus) IsNormalEnd() bool {
+	if s == nil {
+		return true
+	}
+	return s.EndReason == StreamEndReasonDone ||
+		s.EndReason == StreamEndReasonEOF ||
+		s.EndReason == StreamEndReasonHandlerStop
+}
+
+func (s *StreamStatus) Summary() string {
+	if s == nil {
+		return "StreamStatus<nil>"
+	}
+	b := &strings.Builder{}
+	fmt.Fprintf(b, "reason=%s", s.EndReason)
+	if s.EndError != nil {
+		fmt.Fprintf(b, " end_error=%q", s.EndError.Error())
+	}
+	s.mu.Lock()
+	if s.ErrorCount > 0 {
+		fmt.Fprintf(b, " soft_errors=%d", s.ErrorCount)
+	}
+	s.mu.Unlock()
+	return b.String()
+}
@@ -0,0 +1,182 @@
+package common
+
+import (
+	"fmt"
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestStreamStatus_SetEndReason_FirstWins(t *testing.T) {
+	t.Parallel()
+	s := NewStreamStatus()
+
+	s.SetEndReason(StreamEndReasonDone, nil)
+	s.SetEndReason(StreamEndReasonTimeout, nil)
+	s.SetEndReason(StreamEndReasonClientGone, fmt.Errorf("context canceled"))
+
+	assert.Equal(t, StreamEndReasonDone, s.EndReason)
+	assert.Nil(t, s.EndError)
+}
+
+func TestStreamStatus_SetEndReason_WithError(t *testing.T) {
+	t.Parallel()
+	s := NewStreamStatus()
+
+	expectedErr := fmt.Errorf("read: connection reset")
+	s.SetEndReason(StreamEndReasonScannerErr, expectedErr)
+
+	assert.Equal(t, StreamEndReasonScannerErr, s.EndReason)
+	assert.Equal(t, expectedErr, s.EndError)
+}
+
+func TestStreamStatus_SetEndReason_NilSafe(t *testing.T) {
+	t.Parallel()
+	var s *StreamStatus
+	s.SetEndReason(StreamEndReasonDone, nil)
+}
+
+func TestStreamStatus_SetEndReason_Concurrent(t *testing.T) {
+	t.Parallel()
+	s := NewStreamStatus()
+
+	reasons := []StreamEndReason{
+		StreamEndReasonDone,
+		StreamEndReasonTimeout,
+		StreamEndReasonClientGone,
+		StreamEndReasonScannerErr,
+		StreamEndReasonHandlerStop,
+		StreamEndReasonEOF,
+		StreamEndReasonPanic,
+		StreamEndReasonPingFail,
+	}
+
+	var wg sync.WaitGroup
+	for _, r := range reasons {
+		wg.Add(1)
+		go func(reason StreamEndReason) {
+			defer wg.Done()
+			s.SetEndReason(reason, nil)
+		}(r)
+	}
+	wg.Wait()
+
+	assert.NotEqual(t, StreamEndReasonNone, s.EndReason)
+}
+
+func TestStreamStatus_RecordError_Basic(t *testing.T) {
+	t.Parallel()
+	s := NewStreamStatus()
+
+	s.RecordError("bad json")
+	s.RecordError("another bad json")
+	s.RecordError("client gone")
+
+	assert.True(t, s.HasErrors())
+	assert.Equal(t, 3, s.TotalErrorCount())
+	assert.Len(t, s.Errors, 3)
+}
+
+func TestStreamStatus_RecordError_CapAtMax(t *testing.T) {
+	t.Parallel()
+	s := NewStreamStatus()
+
+	for i := 0; i < 30; i++ {
+		s.RecordError(fmt.Sprintf("error_%d", i))
+	}
+
+	assert.Equal(t, maxStreamErrorEntries, len(s.Errors))
+	assert.Equal(t, 30, s.TotalErrorCount())
+}
+
+func TestStreamStatus_RecordError_NilSafe(t *testing.T) {
+	t.Parallel()
+	var s *StreamStatus
+	s.RecordError("should not panic")
+}
+
+func TestStreamStatus_RecordError_Concurrent(t *testing.T) {
+	t.Parallel()
+	s := NewStreamStatus()
+
+	var wg sync.WaitGroup
+	for i := 0; i < 100; i++ {
+		wg.Add(1)
+		go func(idx int) {
+			defer wg.Done()
+			s.RecordError(fmt.Sprintf("error_%d", idx))
+		}(i)
+	}
+	wg.Wait()
+
+	assert.Equal(t, 100, s.TotalErrorCount())
+	assert.LessOrEqual(t, len(s.Errors), maxStreamErrorEntries)
+}
+
+func TestStreamStatus_HasErrors_Empty(t *testing.T) {
+	t.Parallel()
+	s := NewStreamStatus()
+	assert.False(t, s.HasErrors())
+	assert.Equal(t, 0, s.TotalErrorCount())
+}
+
+func TestStreamStatus_HasErrors_NilSafe(t *testing.T) {
+	t.Parallel()
+	var s *StreamStatus
+	assert.False(t, s.HasErrors())
+	assert.Equal(t, 0, s.TotalErrorCount())
+}
+
+func TestStreamStatus_IsNormalEnd(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		reason StreamEndReason
+		normal bool
+	}{
+		{StreamEndReasonDone, true},
+		{StreamEndReasonEOF, true},
+		{StreamEndReasonHandlerStop, true},
+		{StreamEndReasonTimeout, false},
+		{StreamEndReasonClientGone, false},
+		{StreamEndReasonScannerErr, false},
+		{StreamEndReasonPanic, false},
+		{StreamEndReasonPingFail, false},
+		{StreamEndReasonNone, false},
+	}
+	for _, tt := range tests {
+		s := NewStreamStatus()
+		s.SetEndReason(tt.reason, nil)
+		assert.Equal(t, tt.normal, s.IsNormalEnd(), "reason=%s", tt.reason)
+	}
+}
+
+func TestStreamStatus_IsNormalEnd_NilSafe(t *testing.T) {
+	t.Parallel()
+	var s *StreamStatus
+	assert.True(t, s.IsNormalEnd())
+}
+
+func TestStreamStatus_Summary(t *testing.T) {
+	t.Parallel()
+
+	s := NewStreamStatus()
+	s.SetEndReason(StreamEndReasonDone, nil)
+	summary := s.Summary()
+	assert.Contains(t, summary, "reason=done")
+	assert.NotContains(t, summary, "soft_errors")
+
+	s2 := NewStreamStatus()
+	s2.SetEndReason(StreamEndReasonTimeout, nil)
+	s2.RecordError("bad json")
+	s2.RecordError("write failed")
+	summary2 := s2.Summary()
+	assert.Contains(t, summary2, "reason=timeout")
+	assert.Contains(t, summary2, "soft_errors=2")
+}
+
+func TestStreamStatus_Summary_NilSafe(t *testing.T) {
+	t.Parallel()
+	var s *StreamStatus
+	assert.Equal(t, "StreamStatus<nil>", s.Summary())
+}