added sentinel errors

ibetitsmike · ibetitsmike · commit f8dc22ec4e54 · 2025-08-20T12:38:35.000Z
diff --git a/agent/immortalstreams/backedpipe/backed_pipe.go b/agent/immortalstreams/backedpipe/backed_pipe.go
@@ -9,6 +9,15 @@ import (
 	"golang.org/x/xerrors"
 )
 
+var (
+	ErrPipeClosed             = xerrors.New("pipe is closed")
+	ErrPipeAlreadyConnected   = xerrors.New("pipe is already connected")
+	ErrReconnectionInProgress = xerrors.New("reconnection already in progress")
+	ErrReconnectFailed        = xerrors.New("reconnect failed")
+	ErrInvalidSequenceNumber  = xerrors.New("remote sequence number exceeds local sequence")
+	ErrReconnectWriterFailed  = xerrors.New("reconnect writer failed")
+)
+
 const (
 	// Default buffer capacity used by the writer - 64MB
 	DefaultBufferSize = 64 * 1024 * 1024
@@ -90,11 +99,11 @@ func (bp *BackedPipe) Connect(_ context.Context) error { // external ctx ignored
 	defer bp.mu.Unlock()
 
 	if bp.closed {
-		return xerrors.New("pipe is closed")
+		return ErrPipeClosed
 	}
 
 	if bp.connected {
-		return xerrors.New("pipe is already connected")
+		return ErrPipeAlreadyConnected
 	}
 
 	// Use internal context for the actual reconnect operation to ensure
@@ -190,7 +199,7 @@ func (bp *BackedPipe) signalConnectionChange() {
 // reconnectLocked handles the reconnection logic. Must be called with write lock held.
 func (bp *BackedPipe) reconnectLocked() error {
 	if bp.reconnecting {
-		return xerrors.New("reconnection already in progress")
+		return ErrReconnectionInProgress
 	}
 
 	bp.reconnecting = true
@@ -216,14 +225,13 @@ func (bp *BackedPipe) reconnectLocked() error {
 	bp.mu.Lock()
 
 	if err != nil {
-		return xerrors.Errorf("reconnect failed: %w", err)
+		return ErrReconnectFailed
 	}
 
 	// Validate sequence numbers
 	if readerSeqNum > writerSeqNum {
 		_ = conn.Close()
-		return xerrors.Errorf("remote sequence number %d exceeds local sequence %d, cannot replay",
-			readerSeqNum, writerSeqNum)
+		return ErrInvalidSequenceNumber
 	}
 
 	// Reconnect reader and writer
@@ -239,7 +247,7 @@ func (bp *BackedPipe) reconnectLocked() error {
 	err = bp.writer.Reconnect(readerSeqNum, conn)
 	if err != nil {
 		_ = conn.Close()
-		return xerrors.Errorf("reconnect writer: %w", err)
+		return ErrReconnectWriterFailed
 	}
 
 	// Success - update state
diff --git a/agent/immortalstreams/backedpipe/backed_pipe_test.go b/agent/immortalstreams/backedpipe/backed_pipe_test.go
@@ -189,7 +189,7 @@ func TestBackedPipe_ConnectAlreadyConnected(t *testing.T) {
 	// Second connect should fail
 	err = bp.Connect(ctx)
 	require.Error(t, err)
-	require.Contains(t, err.Error(), "already connected")
+	require.ErrorIs(t, err, backedpipe.ErrPipeAlreadyConnected)
 }
 
 func TestBackedPipe_ConnectAfterClose(t *testing.T) {
@@ -206,7 +206,7 @@ func TestBackedPipe_ConnectAfterClose(t *testing.T) {
 
 	err = bp.Connect(ctx)
 	require.Error(t, err)
-	require.Contains(t, err.Error(), "closed")
+	require.ErrorIs(t, err, backedpipe.ErrPipeClosed)
 }
 
 func TestBackedPipe_BasicReadWrite(t *testing.T) {
@@ -501,7 +501,7 @@ func TestBackedPipe_ReconnectFunctionFailure(t *testing.T) {
 
 	err := bp.Connect(ctx)
 	require.Error(t, err)
-	require.Contains(t, err.Error(), "reconnect failed")
+	require.ErrorIs(t, err, backedpipe.ErrReconnectFailed)
 	require.False(t, bp.Connected())
 }
 
diff --git a/agent/immortalstreams/backedpipe/backed_writer.go b/agent/immortalstreams/backedpipe/backed_writer.go
@@ -7,6 +7,15 @@ import (
 	"golang.org/x/xerrors"
 )
 
+var (
+	ErrWriterClosed          = xerrors.New("cannot reconnect closed writer")
+	ErrNilWriter             = xerrors.New("new writer cannot be nil")
+	ErrFutureSequence        = xerrors.New("cannot replay from future sequence")
+	ErrReplayDataUnavailable = xerrors.New("failed to read replay data")
+	ErrReplayFailed          = xerrors.New("replay failed")
+	ErrPartialReplay         = xerrors.New("partial replay")
+)
+
 // BackedWriter wraps an unreliable io.Writer and makes it resilient to disconnections.
 // It maintains a ring buffer of recent writes for replay during reconnection.
 type BackedWriter struct {
@@ -129,16 +138,16 @@ func (bw *BackedWriter) Reconnect(replayFromSeq uint64, newWriter io.Writer) err
 	defer bw.mu.Unlock()
 
 	if bw.closed {
-		return xerrors.New("cannot reconnect closed writer")
+		return ErrWriterClosed
 	}
 
 	if newWriter == nil {
-		return xerrors.New("new writer cannot be nil")
+		return ErrNilWriter
 	}
 
 	// Check if we can replay from the requested sequence number
 	if replayFromSeq > bw.sequenceNum {
-		return xerrors.Errorf("cannot replay from future sequence %d: current sequence is %d", replayFromSeq, bw.sequenceNum)
+		return ErrFutureSequence
 	}
 
 	// Calculate how many bytes we need to replay
@@ -156,7 +165,7 @@ func (bw *BackedWriter) Reconnect(replayFromSeq uint64, newWriter io.Writer) err
 		//nolint:gosec // Safe conversion: replayBytes is calculated from uint64 subtraction
 		replayData, err = bw.buffer.ReadLast(int(replayBytes))
 		if err != nil {
-			return xerrors.Errorf("failed to read replay data: %w", err)
+			return ErrReplayDataUnavailable
 		}
 	}
 
@@ -172,12 +181,12 @@ func (bw *BackedWriter) Reconnect(replayFromSeq uint64, newWriter io.Writer) err
 
 		if err != nil {
 			// Reconnect failed, writer remains nil
-			return xerrors.Errorf("replay failed: %w", err)
+			return ErrReplayFailed
 		}
 
 		if n != len(replayData) {
 			// Reconnect failed, writer remains nil
-			return xerrors.Errorf("partial replay: wrote %d of %d bytes", n, len(replayData))
+			return ErrPartialReplay
 		}
 	}
 
diff --git a/agent/immortalstreams/backedpipe/backed_writer_test.go b/agent/immortalstreams/backedpipe/backed_writer_test.go
@@ -313,7 +313,7 @@ func TestBackedWriter_ReplayFromFutureSequence(t *testing.T) {
 	writer2 := newMockWriter()
 	err = bw.Reconnect(10, writer2) // Future sequence
 	require.Error(t, err)
-	require.Contains(t, err.Error(), "future sequence")
+	require.ErrorIs(t, err, backedpipe.ErrFutureSequence)
 }
 
 func TestBackedWriter_ReplayDataLoss(t *testing.T) {
@@ -336,7 +336,7 @@ func TestBackedWriter_ReplayDataLoss(t *testing.T) {
 	err = bw.Reconnect(0, writer2) // Try to replay from evicted data
 	// With the new error handling, this should fail because we can't read all the data
 	require.Error(t, err)
-	require.Contains(t, err.Error(), "failed to read replay data")
+	require.ErrorIs(t, err, backedpipe.ErrReplayDataUnavailable)
 }
 
 func TestBackedWriter_BufferEviction(t *testing.T) {
@@ -381,7 +381,7 @@ func TestBackedWriter_Close(t *testing.T) {
 	// Reconnect after close should fail
 	err = bw.Reconnect(0, newMockWriter())
 	require.Error(t, err)
-	require.Contains(t, err.Error(), "closed")
+	require.ErrorIs(t, err, backedpipe.ErrWriterClosed)
 }
 
 func TestBackedWriter_CloseIdempotent(t *testing.T) {
@@ -454,7 +454,7 @@ func TestBackedWriter_ReconnectDuringReplay(t *testing.T) {
 
 	err = bw.Reconnect(0, writer2)
 	require.Error(t, err)
-	require.Contains(t, err.Error(), "replay failed")
+	require.ErrorIs(t, err, backedpipe.ErrReplayFailed)
 	require.False(t, bw.Connected())
 }
 
diff --git a/agent/immortalstreams/backedpipe/ring_buffer.go b/agent/immortalstreams/backedpipe/ring_buffer.go
@@ -1,8 +1,6 @@
 package backedpipe
 
-import (
-	"golang.org/x/xerrors"
-)
+import "golang.org/x/xerrors"
 
 // ringBuffer implements an efficient circular buffer with a fixed-size allocation.
 // This implementation is not thread-safe and relies on external synchronization.

Original file line number	Diff line number	Diff line change
`@@ -7,6 +7,15 @@ import (`
`7`	`7`	`"golang.org/x/xerrors"`
`8`	`8`	`)`
`9`	`9`
	`10`	`+var (`
	`11`	`+ ErrWriterClosed = xerrors.New("cannot reconnect closed writer")`
	`12`	`+ ErrNilWriter = xerrors.New("new writer cannot be nil")`
	`13`	`+ ErrFutureSequence = xerrors.New("cannot replay from future sequence")`
	`14`	`+ ErrReplayDataUnavailable = xerrors.New("failed to read replay data")`
	`15`	`+ ErrReplayFailed = xerrors.New("replay failed")`
	`16`	`+ ErrPartialReplay = xerrors.New("partial replay")`
	`17`	`+)`
	`18`	`+`
`10`	`19`	`// BackedWriter wraps an unreliable io.Writer and makes it resilient to disconnections.`
`11`	`20`	`// It maintains a ring buffer of recent writes for replay during reconnection.`
`12`	`21`	`type BackedWriter struct {`
`@@ -129,16 +138,16 @@ func (bw *BackedWriter) Reconnect(replayFromSeq uint64, newWriter io.Writer) err`
`129`	`138`	`defer bw.mu.Unlock()`
`130`	`139`
`131`	`140`	`if bw.closed {`
`132`		`- return xerrors.New("cannot reconnect closed writer")`
	`141`	`+ return ErrWriterClosed`
`133`	`142`	`}`
`134`	`143`
`135`	`144`	`if newWriter == nil {`
`136`		`- return xerrors.New("new writer cannot be nil")`
	`145`	`+ return ErrNilWriter`
`137`	`146`	`}`
`138`	`147`
`139`	`148`	`// Check if we can replay from the requested sequence number`
`140`	`149`	`if replayFromSeq > bw.sequenceNum {`
`141`		`- return xerrors.Errorf("cannot replay from future sequence %d: current sequence is %d", replayFromSeq, bw.sequenceNum)`
	`150`	`+ return ErrFutureSequence`
`142`	`151`	`}`
`143`	`152`
`144`	`153`	`// Calculate how many bytes we need to replay`
`@@ -156,7 +165,7 @@ func (bw *BackedWriter) Reconnect(replayFromSeq uint64, newWriter io.Writer) err`
`156`	`165`	`//nolint:gosec // Safe conversion: replayBytes is calculated from uint64 subtraction`
`157`	`166`	`replayData, err = bw.buffer.ReadLast(int(replayBytes))`
`158`	`167`	`if err != nil {`
`159`		`- return xerrors.Errorf("failed to read replay data: %w", err)`
	`168`	`+ return ErrReplayDataUnavailable`
`160`	`169`	`}`
`161`	`170`	`}`
`162`	`171`
`@@ -172,12 +181,12 @@ func (bw *BackedWriter) Reconnect(replayFromSeq uint64, newWriter io.Writer) err`
`172`	`181`
`173`	`182`	`if err != nil {`
`174`	`183`	`// Reconnect failed, writer remains nil`
`175`		`- return xerrors.Errorf("replay failed: %w", err)`
	`184`	`+ return ErrReplayFailed`
`176`	`185`	`}`
`177`	`186`
`178`	`187`	`if n != len(replayData) {`
`179`	`188`	`// Reconnect failed, writer remains nil`
`180`		`- return xerrors.Errorf("partial replay: wrote %d of %d bytes", n, len(replayData))`
	`189`	`+ return ErrPartialReplay`
`181`	`190`	`}`
`182`	`191`	`}`
`183`	`192`