Bound remote control object reads

internal/adapters/storage/bounded_read.go

@@ -0,0 +1,90 @@
+package storage
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"math"
+	"strings"
+)
+
+// ReadLimitError reports that a remote object exceeded its caller-owned read
+// limit. The limit is enforced against both available object metadata and the
+// bytes returned by the opened object body.
+type ReadLimitError struct {
+	Key      string
+	Limit    int64
+	Observed int64
+}
+
+func (e *ReadLimitError) Error() string {
+	return fmt.Sprintf("object %q exceeds %d-byte read limit (observed at least %d bytes)", e.Key, e.Limit, e.Observed)
+}
+
+// ReadObjectBounded opens one object version and retains at most maxBytes of
+// its content. Object metadata may reject an oversized body early, but a
+// limit-plus-one read always enforces the boundary when transfer begins.
+func ReadObjectBounded(ctx context.Context, store ObjectStore, key string, maxBytes int64) (info ObjectInfo, data []byte, err error) {
+	key = strings.TrimSpace(key)
+	if store == nil {
+		return ObjectInfo{}, nil, fmt.Errorf("read bounded object: store is required")
+	}
+	if key == "" {
+		return ObjectInfo{}, nil, fmt.Errorf("read bounded object: key is required")
+	}
+	if maxBytes <= 0 || maxBytes == math.MaxInt64 {
+		return ObjectInfo{}, nil, fmt.Errorf("read bounded object %q: limit must be between 1 and %d bytes", key, int64(math.MaxInt64-1))
+	}
+	if err := ctx.Err(); err != nil {
+		return ObjectInfo{}, nil, err
+	}
+
+	info, body, err := store.Read(ctx, key)
+	if err != nil {
+		return ObjectInfo{}, nil, err
+	}
+	if body == nil {
+		return ObjectInfo{}, nil, fmt.Errorf("read bounded object %q: store returned no body", key)
+	}
+	defer func() {
+		if closeErr := body.Close(); closeErr != nil {
+			data = nil
+			err = errors.Join(err, fmt.Errorf("close object %q: %w", key, closeErr))
+		}
+	}()
+
+	if info.Size > maxBytes {
+		return info, nil, &ReadLimitError{Key: key, Limit: maxBytes, Observed: info.Size}
+	}
+
+	data, err = io.ReadAll(io.LimitReader(contextReader{ctx: ctx, reader: body}, maxBytes+1))
+	if err != nil {
+		return info, nil, err
+	}
+	if err := ctx.Err(); err != nil {
+		return info, nil, err
+	}
+	if int64(len(data)) > maxBytes {
+		return info, nil, &ReadLimitError{Key: key, Limit: maxBytes, Observed: int64(len(data))}
+	}
+	return info, data, nil
+}
+
+type contextReader struct {
+	ctx    context.Context
+	reader io.Reader
+}
+
+func (r contextReader) Read(p []byte) (int, error) {
+	if err := r.ctx.Err(); err != nil {
+		return 0, err
+	}
+	n, err := r.reader.Read(p)
+	if err == nil {
+		if contextErr := r.ctx.Err(); contextErr != nil {
+			return n, contextErr
+		}
+	}
+	return n, err
+}

internal/adapters/storage/bounded_read_test.go

@@ -0,0 +1,135 @@
+package storage
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"testing"
+)
+
+func TestReadObjectBoundedAcceptsExactLimitWithAbsentSizeMetadata(t *testing.T) {
+	body := &trackingReadCloser{reader: bytes.NewReader([]byte("12345678")), chunkSize: 2}
+	store := &boundedReadStore{read: func(context.Context, string) (ObjectInfo, io.ReadCloser, error) {
+		return ObjectInfo{Key: "control.json", ETag: "generation"}, body, nil
+	}}
+
+	info, data, err := ReadObjectBounded(context.Background(), store, "control.json", 8)
+	if err != nil {
+		t.Fatalf("ReadObjectBounded() error = %v", err)
+	}
+	if string(data) != "12345678" || info.ETag != "generation" {
+		t.Fatalf("ReadObjectBounded() = (%#v, %q), want opened object metadata and bytes", info, data)
+	}
+	if !body.closed {
+		t.Fatal("object body was not closed")
+	}
+}
+
+func TestReadObjectBoundedRejectsLimitPlusOneDespiteMissingOrInaccurateMetadata(t *testing.T) {
+	tests := []struct {
+		name         string
+		metadataSize int64
+	}{
+		{name: "missing", metadataSize: 0},
+		{name: "inaccurate", metadataSize: 2},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			body := &trackingReadCloser{reader: bytes.NewReader([]byte("123456789")), chunkSize: 1}
+			store := &boundedReadStore{read: func(context.Context, string) (ObjectInfo, io.ReadCloser, error) {
+				return ObjectInfo{Key: "control.json", Size: test.metadataSize}, body, nil
+			}}
+
+			_, data, err := ReadObjectBounded(context.Background(), store, "control.json", 8)
+			var limitErr *ReadLimitError
+			if !errors.As(err, &limitErr) {
+				t.Fatalf("ReadObjectBounded() error = %v, want ReadLimitError", err)
+			}
+			if data != nil || body.bytesRead != 9 || !body.closed {
+				t.Fatalf("data=%q bytes read=%d closed=%t, want nil, 9, true", data, body.bytesRead, body.closed)
+			}
+		})
+	}
+}
+
+func TestReadObjectBoundedRejectsOversizedMetadataBeforeTransfer(t *testing.T) {
+	body := &trackingReadCloser{reader: bytes.NewReader([]byte("small"))}
+	store := &boundedReadStore{read: func(context.Context, string) (ObjectInfo, io.ReadCloser, error) {
+		return ObjectInfo{Key: "control.json", Size: 9}, body, nil
+	}}
+
+	_, _, err := ReadObjectBounded(context.Background(), store, "control.json", 8)
+	var limitErr *ReadLimitError
+	if !errors.As(err, &limitErr) {
+		t.Fatalf("ReadObjectBounded() error = %v, want ReadLimitError", err)
+	}
+	if body.bytesRead != 0 || !body.closed {
+		t.Fatalf("bytes read=%d closed=%t, want zero-byte transfer and closed body", body.bytesRead, body.closed)
+	}
+}
+
+func TestReadObjectBoundedPropagatesCancellationAndClosesBody(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	body := &trackingReadCloser{reader: bytes.NewReader([]byte("12345678")), chunkSize: 1, afterRead: cancel}
+	store := &boundedReadStore{read: func(context.Context, string) (ObjectInfo, io.ReadCloser, error) {
+		return ObjectInfo{Key: "control.json"}, body, nil
+	}}
+
+	_, data, err := ReadObjectBounded(ctx, store, "control.json", 8)
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("ReadObjectBounded() error = %v, want context cancellation", err)
+	}
+	if data != nil || body.bytesRead != 1 || !body.closed {
+		t.Fatalf("data=%q bytes read=%d closed=%t, want nil, 1, true", data, body.bytesRead, body.closed)
+	}
+}
+
+func TestReadObjectBoundedReturnsCloseFailure(t *testing.T) {
+	closeErr := errors.New("close failed")
+	body := &trackingReadCloser{reader: bytes.NewReader([]byte("ok")), closeErr: closeErr}
+	store := &boundedReadStore{read: func(context.Context, string) (ObjectInfo, io.ReadCloser, error) {
+		return ObjectInfo{Key: "control.json", Size: 2}, body, nil
+	}}
+
+	_, data, err := ReadObjectBounded(context.Background(), store, "control.json", 8)
+	if !errors.Is(err, closeErr) || data != nil || !body.closed {
+		t.Fatalf("data=%q error=%v closed=%t, want close failure and no retained data", data, err, body.closed)
+	}
+}
+
+type boundedReadStore struct {
+	ObjectStore
+	read func(context.Context, string) (ObjectInfo, io.ReadCloser, error)
+}
+
+func (s *boundedReadStore) Read(ctx context.Context, key string) (ObjectInfo, io.ReadCloser, error) {
+	return s.read(ctx, key)
+}
+
+type trackingReadCloser struct {
+	reader    io.Reader
+	chunkSize int
+	afterRead func()
+	closeErr  error
+	bytesRead int
+	closed    bool
+}
+
+func (r *trackingReadCloser) Read(p []byte) (int, error) {
+	if r.chunkSize > 0 && len(p) > r.chunkSize {
+		p = p[:r.chunkSize]
+	}
+	n, err := r.reader.Read(p)
+	r.bytesRead += n
+	if n > 0 && r.afterRead != nil {
+		r.afterRead()
+		r.afterRead = nil
+	}
+	return n, err
+}
+
+func (r *trackingReadCloser) Close() error {
+	r.closed = true
+	return r.closeErr
+}

internal/adapters/storage/fake.go

@@ -22,6 +22,7 @@ type FakeBackend struct {
 	Objects   map[string]FakeObject
 	Uploads   []FakeUploadCall
 	Downloads []FakeDownloadCall
+	Reads     []FakeReadCall
 
 	ListErr      error
 	DownloadErr  error
@@ -45,6 +46,11 @@ type FakeDownloadCall struct {
 	Bytes     int64
 }
 
+// FakeReadCall captures one opened object in call order.
+type FakeReadCall struct {
+	Key string
+}
+
 // FakeObject is a deterministic fake object-store record.
 type FakeObject struct {
 	Key          string
@@ -127,6 +133,9 @@ func (f *FakeBackend) Read(ctx context.Context, key string) (ObjectInfo, io.Read
 	if !ok {
 		return ObjectInfo{}, nil, fmt.Errorf("read object %q: %w", normalizedKey, os.ErrNotExist)
 	}
+	f.mu.Lock()
+	f.Reads = append(f.Reads, FakeReadCall{Key: normalizedKey})
+	f.mu.Unlock()
 	return ObjectInfo{Key: obj.Key, Size: int64(len(obj.Data)), ETag: obj.ETag, LastModified: obj.LastModified}, io.NopCloser(bytes.NewReader(obj.Data)), nil
 }
 

internal/adapters/storage/s3_backend_test.go

@@ -23,8 +23,11 @@ type fakeS3API struct {
 	listErr     error
 	listCalls   int
 
-	getBody io.ReadCloser
-	getErr  error
+	getBody         io.ReadCloser
+	getErr          error
+	getSize         *int64
+	getETag         *string
+	getLastModified *time.Time
 
 	putOut *s3.PutObjectOutput
 	putErr error
@@ -99,7 +102,7 @@ func (f *fakeS3API) GetObject(_ context.Context, params *s3.GetObjectInput, _ ..
 	if body == nil {
 		body = io.NopCloser(strings.NewReader(""))
 	}
-	return &s3.GetObjectOutput{Body: body}, nil
+	return &s3.GetObjectOutput{Body: body, ContentLength: f.getSize, ETag: f.getETag, LastModified: f.getLastModified}, nil
 }
 
 func (f *fakeS3API) PutObject(_ context.Context, params *s3.PutObjectInput, _ ...func(*s3.Options)) (*s3.PutObjectOutput, error) {
@@ -171,6 +174,33 @@ func TestS3BackendDownloadCreatesParentDirectory(t *testing.T) {
 	}
 }
 
+func TestS3BackendReadReturnsOpenedObjectMetadata(t *testing.T) {
+	lastModified := time.Date(2026, 8, 11, 1, 2, 3, 0, time.UTC)
+	client := &fakeS3API{
+		getBody:         io.NopCloser(strings.NewReader("locks")),
+		getSize:         int64Ptr(5),
+		getETag:         strPtr(`"generation"`),
+		getLastModified: &lastModified,
+	}
+	backend := &S3Backend{bucket: "bucket-1", client: client}
+
+	info, body, err := backend.Read(context.Background(), `sessions\locks.yml`)
+	if err != nil {
+		t.Fatalf("Read() error = %v", err)
+	}
+	data, readErr := io.ReadAll(body)
+	closeErr := body.Close()
+	if readErr != nil || closeErr != nil {
+		t.Fatalf("read body error=%v close error=%v", readErr, closeErr)
+	}
+	if info.Key != "sessions/locks.yml" || info.Size != 5 || info.ETag != "generation" || info.LastModified == nil || !info.LastModified.Equal(lastModified) {
+		t.Fatalf("Read() info = %#v, want opened object metadata", info)
+	}
+	if string(data) != "locks" || client.lastGet == nil || *client.lastGet.Key != "sessions/locks.yml" {
+		t.Fatalf("Read() data=%q request=%#v", data, client.lastGet)
+	}
+}
+
 func TestS3BackendUploadAndExists(t *testing.T) {
 	client := &fakeS3API{putOut: &s3.PutObjectOutput{ETag: strPtr(`"etag123"`)}}
 	backend := &S3Backend{bucket: "bucket-1", client: client}