fix(cache): support validated ranged proxy downloads

Author: Mmx233

README.md

@@ -162,6 +162,17 @@ composition; verify lifecycle support when using an S3-compatible endpoint.
 
 Local signed upload URLs expire after 24 hours; signed download URLs and S3 direct download URLs expire after 10 minutes.
 
+Keep `ENABLE_DIRECT_DOWNLOADS=false` for Azure v2-compatible clients that may
+resume at a nonzero offset. Those clients send `x-ms-range`, which S3 does not
+translate to its standard `Range` header; proxied downloads perform the required
+translation and validation.
+
+Proxied download URLs support `HEAD`, standard `Range`, and Azure's
+`x-ms-range` (which takes precedence when both range fields are present).
+Successful byte ranges return a single `206` response with exact
+`Content-Range`; unsatisfiable ranges return `416`. Malformed ranges, including
+the unsafe `x-ms-range` plus `If-Range` combination, fail closed with `400`.
+
 Eligible caches are presigned directly; layouts that do not satisfy the
 backend's multipart constraints transparently fall back to server-proxied
 downloads.

e2e/cache_flow_test.go

@@ -69,6 +69,22 @@ func TestSQLiteFilesystemSaveAndRestore(t *testing.T) {
 
 	require.Equal(t, "cache-content", downloadCache(t, router, downloadURL))
 
+	rangeReq := httptest.NewRequest(http.MethodGet, downloadURL.RequestURI(), nil)
+	rangeReq.Header.Set("X-Ms-Range", "bytes=2-")
+	rangeRec := httptest.NewRecorder()
+	router.ServeHTTP(rangeRec, rangeReq)
+	require.Equal(t, http.StatusPartialContent, rangeRec.Code)
+	require.Equal(t, "bytes 2-12/13", rangeRec.Header().Get("Content-Range"))
+	require.Equal(t, "che-content", rangeRec.Body.String())
+
+	headReq := httptest.NewRequest(http.MethodHead, downloadURL.RequestURI(), nil)
+	headRec := httptest.NewRecorder()
+	router.ServeHTTP(headRec, headReq)
+	require.Equal(t, http.StatusOK, headRec.Code)
+	require.Equal(t, "13", headRec.Header().Get("Content-Length"))
+	require.Equal(t, "bytes", headRec.Header().Get("Accept-Ranges"))
+	require.Empty(t, headRec.Body.String())
+
 	legacyURL := *downloadURL
 	legacyQuery := legacyURL.Query()
 	legacyQuery.Set("signature", legacyQuery.Get("sig"))

internal/cache/byte_range.go

@@ -0,0 +1,94 @@
+package cache
+
+import (
+	"errors"
+	"fmt"
+)
+
+var ErrRangeNotSatisfiable = errors.New("requested byte range is not satisfiable")
+
+type byteRangeKind uint8
+
+const (
+	closedByteRange byteRangeKind = iota
+	openEndedByteRange
+	suffixByteRange
+)
+
+// ByteRange is a parsed, representation-independent byte range. Constructors
+// keep HTTP syntax out of the cache package while preserving the distinction
+// between closed, open-ended, and suffix ranges until the total size is known.
+type ByteRange struct {
+	kind   byteRangeKind
+	first  int64
+	last   int64
+	suffix int64
+}
+
+func ClosedByteRange(first, last int64) ByteRange {
+	return ByteRange{kind: closedByteRange, first: first, last: last}
+}
+
+func OpenEndedByteRange(first int64) ByteRange {
+	return ByteRange{kind: openEndedByteRange, first: first}
+}
+
+func SuffixByteRange(length int64) ByteRange {
+	return ByteRange{kind: suffixByteRange, suffix: length}
+}
+
+type DownloadRange struct {
+	Offset int64
+	Count  int64
+}
+
+type RangeNotSatisfiableError struct {
+	SizeBytes int64
+}
+
+func (e *RangeNotSatisfiableError) Error() string {
+	return fmt.Sprintf("%s: size %d", ErrRangeNotSatisfiable, e.SizeBytes)
+}
+
+func (e *RangeNotSatisfiableError) Unwrap() error {
+	return ErrRangeNotSatisfiable
+}
+
+func resolveByteRanges(ranges []ByteRange, size int64) (DownloadRange, error) {
+	if size < 0 {
+		return DownloadRange{}, fmt.Errorf("invalid cache size %d", size)
+	}
+	for _, candidate := range ranges {
+		switch candidate.kind {
+		case closedByteRange:
+			if candidate.first < 0 || candidate.last < candidate.first {
+				return DownloadRange{}, fmt.Errorf("invalid closed byte range %d-%d", candidate.first, candidate.last)
+			}
+			if candidate.first >= size {
+				continue
+			}
+			last := min(candidate.last, size-1)
+			return DownloadRange{Offset: candidate.first, Count: last - candidate.first + 1}, nil
+		case openEndedByteRange:
+			if candidate.first < 0 {
+				return DownloadRange{}, fmt.Errorf("invalid open-ended byte range %d-", candidate.first)
+			}
+			if candidate.first >= size {
+				continue
+			}
+			return DownloadRange{Offset: candidate.first, Count: size - candidate.first}, nil
+		case suffixByteRange:
+			if candidate.suffix < 0 {
+				return DownloadRange{}, fmt.Errorf("invalid suffix byte range -%d", candidate.suffix)
+			}
+			if candidate.suffix == 0 || size == 0 {
+				continue
+			}
+			count := min(candidate.suffix, size)
+			return DownloadRange{Offset: size - count, Count: count}, nil
+		default:
+			return DownloadRange{}, fmt.Errorf("invalid byte range kind %d", candidate.kind)
+		}
+	}
+	return DownloadRange{}, &RangeNotSatisfiableError{SizeBytes: size}
+}

internal/cache/byte_range_test.go

@@ -0,0 +1,48 @@
+package cache
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestResolveByteRangesSelectsFirstSatisfiableRange(t *testing.T) {
+	tests := []struct {
+		name   string
+		ranges []ByteRange
+		size   int64
+		want   DownloadRange
+	}{
+		{name: "closed clamps end", ranges: []ByteRange{ClosedByteRange(2, 20)}, size: 9, want: DownloadRange{Offset: 2, Count: 7}},
+		{name: "open ended", ranges: []ByteRange{OpenEndedByteRange(2)}, size: 9, want: DownloadRange{Offset: 2, Count: 7}},
+		{name: "suffix", ranges: []ByteRange{SuffixByteRange(3)}, size: 9, want: DownloadRange{Offset: 6, Count: 3}},
+		{name: "large suffix", ranges: []ByteRange{SuffixByteRange(20)}, size: 9, want: DownloadRange{Offset: 0, Count: 9}},
+		{name: "later satisfiable", ranges: []ByteRange{ClosedByteRange(99, 100), ClosedByteRange(1, 2)}, size: 9, want: DownloadRange{Offset: 1, Count: 2}},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			got, err := resolveByteRanges(test.ranges, test.size)
+			require.NoError(t, err)
+			require.Equal(t, test.want, got)
+		})
+	}
+}
+
+func TestResolveByteRangesReportsUnsatisfiableSize(t *testing.T) {
+	for _, test := range []struct {
+		name string
+		spec ByteRange
+		size int64
+	}{
+		{name: "start at end", spec: OpenEndedByteRange(4), size: 4},
+		{name: "zero suffix", spec: SuffixByteRange(0), size: 4},
+		{name: "empty object", spec: SuffixByteRange(1), size: 0},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			_, err := resolveByteRanges([]ByteRange{test.spec}, test.size)
+			var rangeErr *RangeNotSatisfiableError
+			require.ErrorAs(t, err, &rangeErr)
+			require.Equal(t, test.size, rangeErr.SizeBytes)
+		})
+	}
+}