Add fixed-size circular byte buffer

Introduce RingFixed, a fixed-capacity circular byte buffer that
implements io.Writer. When full, new writes overwrite the oldest
data, retaining only the most recent N bytes. Useful for capturing
the tail of command output or log streams where memory must be bounded.

Signed-off-by: Davanum Srinivas <davanum@gmail.com>

Author: dims

buffer/ring_fixed.go

@@ -0,0 +1,125 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package buffer
+
+import (
+	"errors"
+)
+
+// ErrInvalidSize is returned when a non-positive size is provided to NewRingFixed.
+var ErrInvalidSize = errors.New("size must be positive")
+
+// RingFixed implements a fixed-size circular byte buffer. New writes overwrite
+// older data, such that for a buffer of size N, only the last N bytes written
+// are retained. It implements io.Writer.
+// Not thread safe.
+type RingFixed struct {
+	data        []byte
+	size        int
+	writeCursor int
+	written     int64
+}
+
+// NewRingFixed creates a new fixed-size circular byte buffer of the given size.
+// The size must be greater than 0.
+func NewRingFixed(size int) (*RingFixed, error) {
+	if size <= 0 {
+		return nil, ErrInvalidSize
+	}
+	return &RingFixed{
+		data: make([]byte, size),
+		size: size,
+	}, nil
+}
+
+// Write writes p to the buffer, overwriting older data if necessary.
+// It always returns len(p), nil.
+func (r *RingFixed) Write(p []byte) (int, error) {
+	originalLen := len(p)
+	r.written += int64(originalLen)
+
+	// If the input is larger than our buffer, only keep the last 'size' bytes
+	if originalLen > r.size {
+		p = p[originalLen-r.size:]
+	}
+
+	// Copy data, handling wrap-around
+	n := len(p)
+	remain := r.size - r.writeCursor
+	if n <= remain {
+		copy(r.data[r.writeCursor:], p)
+	} else {
+		copy(r.data[r.writeCursor:], p[:remain])
+		copy(r.data, p[remain:])
+	}
+
+	r.writeCursor = (r.writeCursor + n) % r.size
+	return originalLen, nil
+}
+
+// Bytes returns the contents of the buffer in the order they were written.
+// The returned slice should not be modified by the caller.
+func (r *RingFixed) Bytes() []byte {
+	if r.written == 0 {
+		return nil
+	}
+
+	// Buffer hasn't wrapped yet
+	if r.written < int64(r.size) {
+		return r.data[:r.writeCursor]
+	}
+
+	// Buffer has wrapped - need to return data in correct order
+	// Data from writeCursor to end is oldest, data from 0 to writeCursor is newest
+	if r.writeCursor == 0 {
+		return r.data
+	}
+
+	out := make([]byte, r.size)
+	copy(out, r.data[r.writeCursor:])
+	copy(out[r.size-r.writeCursor:], r.data[:r.writeCursor])
+	return out
+}
+
+// String returns the contents of the buffer as a string.
+func (r *RingFixed) String() string {
+	return string(r.Bytes())
+}
+
+// Size returns the capacity of the buffer.
+func (r *RingFixed) Size() int {
+	return r.size
+}
+
+// Len returns the number of bytes currently stored in the buffer.
+func (r *RingFixed) Len() int {
+	if r.written < int64(r.size) {
+		return int(r.written)
+	}
+	return r.size
+}
+
+// TotalWritten returns the total number of bytes ever written to the buffer.
+func (r *RingFixed) TotalWritten() int64 {
+	return r.written
+}
+
+// Reset clears the buffer, discarding all data.
+func (r *RingFixed) Reset() {
+	r.writeCursor = 0
+	r.written = 0
+}

buffer/ring_fixed_test.go

@@ -0,0 +1,178 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package buffer
+
+import (
+	"io"
+	"testing"
+)
+
+func TestRingFixedNew(t *testing.T) {
+	t.Parallel()
+
+	buf, err := NewRingFixed(10)
+	if err != nil {
+		t.Errorf("size 10: unexpected error: %v", err)
+	}
+	if buf.Size() != 10 {
+		t.Errorf("Size() = %d, want 10", buf.Size())
+	}
+	if _, err := NewRingFixed(1); err != nil {
+		t.Errorf("size 1: unexpected error: %v", err)
+	}
+	if _, err := NewRingFixed(0); err != ErrInvalidSize {
+		t.Errorf("size 0: expected ErrInvalidSize, got %v", err)
+	}
+	if _, err := NewRingFixed(-1); err != ErrInvalidSize {
+		t.Errorf("size -1: expected ErrInvalidSize, got %v", err)
+	}
+}
+
+func TestRingFixedWriterInterface(t *testing.T) {
+	t.Parallel()
+	var _ io.Writer = &RingFixed{}
+}
+
+func TestRingFixedWrite(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name         string
+		size         int
+		writes       []string
+		wantString   string
+		wantLen      int
+		wantWritten  int64
+	}{
+		{"short write", 1024, []string{"hello world"}, "hello world", 11, 11},
+		{"full write", 11, []string{"hello world"}, "hello world", 11, 11},
+		{"long write", 6, []string{"hello world"}, " world", 6, 11},
+		{"huge write", 3, []string{"hello world"}, "rld", 3, 11},
+		{"empty write", 10, []string{"hello", ""}, "hello", 5, 5},
+		{"size one", 1, []string{"a", "b", "xyz"}, "z", 1, 5},
+		{"overwrite", 10, []string{"0123456789", "abc"}, "3456789abc", 10, 13},
+		{"multiple small", 10, []string{"aa", "bb", "cc", "dd", "ee", "ff"}, "bbccddeeff", 10, 12},
+		{"many single bytes", 3, []string{"h", "e", "l", "l", "o", " ", "w", "o", "r", "l", "d"}, "rld", 3, 11},
+		{
+			"multi part",
+			16,
+			[]string{"hello world\n", "this is a test\n", "my cool input\n"},
+			"t\nmy cool input\n",
+			16,
+			41,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			buf, _ := NewRingFixed(tt.size)
+			for _, w := range tt.writes {
+				buf.Write([]byte(w))
+			}
+			if got := buf.String(); got != tt.wantString {
+				t.Errorf("String() = %q, want %q", got, tt.wantString)
+			}
+			if got := buf.Len(); got != tt.wantLen {
+				t.Errorf("Len() = %d, want %d", got, tt.wantLen)
+			}
+			if got := buf.TotalWritten(); got != tt.wantWritten {
+				t.Errorf("TotalWritten() = %d, want %d", got, tt.wantWritten)
+			}
+		})
+	}
+}
+
+func TestRingFixedWriteReturnValue(t *testing.T) {
+	t.Parallel()
+
+	buf, _ := NewRingFixed(5)
+
+	// Write returns original length even when truncated
+	if n, err := buf.Write([]byte("hello world")); n != 11 || err != nil {
+		t.Errorf("Write() = (%d, %v), want (11, nil)", n, err)
+	}
+}
+
+func TestRingFixedReset(t *testing.T) {
+	t.Parallel()
+
+	buf, _ := NewRingFixed(4)
+	buf.Write([]byte("hello world\n"))
+	buf.Write([]byte("this is a test\n"))
+	buf.Reset()
+
+	if buf.Len() != 0 || buf.TotalWritten() != 0 || buf.Bytes() != nil {
+		t.Errorf("after Reset: Len=%d, TotalWritten=%d, Bytes=%v; want 0, 0, nil",
+			buf.Len(), buf.TotalWritten(), buf.Bytes())
+	}
+
+	// Write after reset
+	buf.Write([]byte("hello"))
+	if got := buf.String(); got != "ello" {
+		t.Errorf("after Reset+Write: String() = %q, want %q", got, "ello")
+	}
+}
+
+func TestRingFixedBytes(t *testing.T) {
+	t.Parallel()
+
+	buf, _ := NewRingFixed(10)
+
+	// Empty
+	if buf.Bytes() != nil {
+		t.Errorf("empty buffer: Bytes() = %v, want nil", buf.Bytes())
+	}
+
+	// Partial fill - returns slice of internal buffer
+	buf.Write([]byte("hello"))
+	if got := string(buf.Bytes()); got != "hello" {
+		t.Errorf("partial fill: Bytes() = %q, want %q", got, "hello")
+	}
+
+	// Exact fill at cursor 0 - returns internal buffer directly
+	buf.Reset()
+	buf.Write([]byte("0123456789"))
+	if got := string(buf.Bytes()); got != "0123456789" {
+		t.Errorf("exact fill: Bytes() = %q, want %q", got, "0123456789")
+	}
+
+	// Wrapped - returns new slice with reordered data
+	buf.Write([]byte("ab"))
+	if got := string(buf.Bytes()); got != "23456789ab" {
+		t.Errorf("wrapped: Bytes() = %q, want %q", got, "23456789ab")
+	}
+}
+
+func BenchmarkRingFixed_Write(b *testing.B) {
+	b.ReportAllocs()
+	buf, _ := NewRingFixed(1024)
+	data := make([]byte, 100)
+
+	for i := 0; i < b.N; i++ {
+		buf.Write(data)
+	}
+}
+
+func BenchmarkRingFixed_Bytes(b *testing.B) {
+	b.ReportAllocs()
+	buf, _ := NewRingFixed(1024)
+	buf.Write(make([]byte, 2000)) // Ensure buffer is wrapped
+
+	for i := 0; i < b.N; i++ {
+		_ = buf.Bytes()
+	}
+}