Add fixed-size circular buffer

This adds TypedRingFixed, a generic circular buffer with a fixed capacity.
When the buffer is full, new writes overwrite the oldest entries, keeping
only the most recent N elements. This is handy for scenarios like capturing
the tail of command output or log streams where memory needs to stay bounded.

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

Author: dims

buffer/ring_fixed.go

@@ -0,0 +1,116 @@
+/*
+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 indicates size must be > 0
+var ErrInvalidSize = errors.New("size must be positive")
+
+// TypedRingFixed is a fixed-size circular buffer for elements of type T.
+// Writes overwrite older data, keeping only the last N elements.
+// Not thread safe.
+type TypedRingFixed[T any] struct {
+	data        []T
+	size        int
+	writeCursor int
+	written     int64
+}
+
+// NewTypedRingFixed creates a circular buffer with the given capacity (must be > 0).
+func NewTypedRingFixed[T any](size int) (*TypedRingFixed[T], error) {
+	if size <= 0 {
+		return nil, ErrInvalidSize
+	}
+	return &TypedRingFixed[T]{
+		data: make([]T, size),
+		size: size,
+	}, nil
+}
+
+// Write writes p to the buffer, overwriting old data if needed. Returns len(p).
+func (r *TypedRingFixed[T]) Write(p []T) int {
+	originalLen := len(p)
+	r.written += int64(originalLen)
+
+	// If the input is larger than our buffer, only keep the last 'size' elements
+	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
+}
+
+// Slice returns buffer contents in write order. Don't modify the returned slice.
+func (r *TypedRingFixed[T]) Slice() []T {
+	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([]T, r.size)
+	copy(out, r.data[r.writeCursor:])
+	copy(out[r.size-r.writeCursor:], r.data[:r.writeCursor])
+	return out
+}
+
+// Size returns the buffer capacity.
+func (r *TypedRingFixed[T]) Size() int {
+	return r.size
+}
+
+// Len returns how many elements are currently in the buffer.
+func (r *TypedRingFixed[T]) Len() int {
+	if r.written < int64(r.size) {
+		return int(r.written)
+	}
+	return r.size
+}
+
+// TotalWritten returns total elements ever written (including overwritten ones).
+func (r *TypedRingFixed[T]) TotalWritten() int64 {
+	return r.written
+}
+
+// Reset clears the buffer.
+func (r *TypedRingFixed[T]) Reset() {
+	r.writeCursor = 0
+	r.written = 0
+}