fix(compat): /range supports duration parameter (#203)

I started to take a run at the `/range` incompatibilities identified in
#172 but in the course of
working on this I have decided, for now, that perfect compatibility with
the original httpbin implementation is not worth the effort.

So here we do (kinda) support the `?duration` parameter, but it
effectively acts more as a delay before the entire response is written.
We also add drive-by tests to ensure that we're properly support
requests for multiple ranges (which the original httpbin _does not_
correctly support).

Properly supporting both `?chunk_size` and `?duration` parameters would
require fully re-implementing the stdlib's built-in support for range
requests, which would get complicated where splitting the response into
chunks spread over a given duration intersects with constructing proper
multipart responses for multiple range requests.

For now, I'm happy to leave the implementation _mostly_ as-is.

Author: mccutchen

httpbin/handlers.go

@@ -743,15 +743,37 @@ func (h *HTTPBin) Drip(w http.ResponseWriter, r *http.Request) {
 
 // Range returns up to N bytes, with support for HTTP Range requests.
 //
-// This departs from httpbin by not supporting the chunk_size or duration
-// parameters.
+// This departs from original httpbin in a few ways:
+//
+//   - param `chunk_size` IS NOT supported
+//
+//   - param `duration` IS supported, but functions more as a delay before the
+//     whole response is written
+//
+//   - multiple ranges ARE correctly supported (i.e. `Range: bytes=0-1,2-3`
+//     will return a multipart/byteranges response)
+//
+// Most of the heavy lifting is done by the stdlib's http.ServeContent, which
+// handles range requests automatically. Supporting chunk sizes would require
+// an extensive reimplementation, especially to support multiple ranges for
+// correctness. For now, we choose not to take that work on.
 func (h *HTTPBin) Range(w http.ResponseWriter, r *http.Request) {
 	numBytes, err := strconv.ParseInt(r.PathValue("numBytes"), 10, 64)
 	if err != nil {
 		writeError(w, http.StatusBadRequest, fmt.Errorf("invalid count: %w", err))
 		return
 	}
 
+	var duration time.Duration
+	if durationVal := r.URL.Query().Get("duration"); durationVal != "" {
+		var err error
+		duration, err = parseBoundedDuration(r.URL.Query().Get("duration"), 0, h.MaxDuration)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, fmt.Errorf("invalid duration: %w", err))
+			return
+		}
+	}
+
 	w.Header().Add("ETag", fmt.Sprintf("range%d", numBytes))
 	w.Header().Add("Accept-Ranges", "bytes")
 
@@ -760,7 +782,7 @@ func (h *HTTPBin) Range(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	content := newSyntheticByteStream(numBytes, func(offset int64) byte {
+	content := newSyntheticByteStream(numBytes, duration, func(offset int64) byte {
 		return byte(97 + (offset % 26))
 	})
 	var modtime time.Time

httpbin/handlers_test.go

@@ -11,6 +11,7 @@ import (
 	"fmt"
 	"io"
 	"log/slog"
+	"mime"
 	"mime/multipart"
 	"net"
 	"net/http"
@@ -2303,6 +2304,7 @@ func TestRange(t *testing.T) {
 		assert.Header(t, resp, "Accept-Ranges", "bytes")
 		assert.Header(t, resp, "Content-Length", "15")
 		assert.Header(t, resp, "Content-Range", "bytes 10-24/100")
+		assert.Header(t, resp, "Content-Type", textContentType)
 		assert.BodyEquals(t, resp, "klmnopqrstuvwxy")
 	})
 
@@ -2353,6 +2355,69 @@ func TestRange(t *testing.T) {
 		assert.BodyEquals(t, resp, "vwxyz")
 	})
 
+	t.Run("ok_range_with_duration", func(t *testing.T) {
+		t.Parallel()
+
+		url := "/range/100?duration=100ms"
+		req := newTestRequest(t, "GET", url)
+		req.Header.Add("Range", "bytes=10-24")
+
+		start := time.Now()
+		resp := must.DoReq(t, client, req)
+		elapsed := time.Since(start)
+
+		assert.StatusCode(t, resp, http.StatusPartialContent)
+		assert.Header(t, resp, "ETag", "range100")
+		assert.Header(t, resp, "Accept-Ranges", "bytes")
+		assert.Header(t, resp, "Content-Length", "15")
+		assert.Header(t, resp, "Content-Range", "bytes 10-24/100")
+		assert.Header(t, resp, "Content-Type", textContentType)
+		assert.BodyEquals(t, resp, "klmnopqrstuvwxy")
+		assert.DurationRange(t, elapsed, 100*time.Millisecond, 150*time.Millisecond)
+	})
+
+	t.Run("ok_multiple_ranges", func(t *testing.T) {
+		t.Parallel()
+
+		url := "/range/100"
+		req := newTestRequest(t, "GET", url)
+		req.Header.Add("Range", "bytes=10-24, 50-64")
+
+		resp := must.DoReq(t, client, req)
+		assert.StatusCode(t, resp, http.StatusPartialContent)
+		assert.Header(t, resp, "ETag", "range100")
+		assert.Header(t, resp, "Accept-Ranges", "bytes")
+
+		mediatype, params, err := mime.ParseMediaType(resp.Header.Get("Content-Type"))
+		assert.NilError(t, err)
+		assert.Equal(t, mediatype, "multipart/byteranges", "incorrect content type")
+
+		expectRanges := []struct {
+			contentRange string
+			body         string
+		}{
+			{"bytes 10-24/100", "klmnopqrstuvwxy"},
+			{"bytes 50-64/100", "yzabcdefghijklm"},
+		}
+		mpr := multipart.NewReader(resp.Body, params["boundary"])
+		for i := 0; ; i++ {
+			p, err := mpr.NextPart()
+			if err == io.EOF {
+				break
+			}
+			assert.NilError(t, err)
+
+			ct := p.Header.Get("Content-Type")
+			assert.Equal(t, ct, textContentType, "incorrect content type")
+
+			cr := p.Header.Get("Content-Range")
+			assert.Equal(t, cr, expectRanges[i].contentRange, "incorrect Content-Range header")
+
+			part := must.ReadAll(t, p)
+			assert.Equal(t, string(part), expectRanges[i].body, "incorrect range part")
+		}
+	})
+
 	t.Run("err_range_out_of_bounds", func(t *testing.T) {
 		t.Parallel()
 
@@ -2400,6 +2465,11 @@ func TestRange(t *testing.T) {
 		{"/range/foo", http.StatusBadRequest},
 		{"/range/1.5", http.StatusBadRequest},
 		{"/range/-1", http.StatusBadRequest},
+
+		// invalid durations
+		{"/range/100?duration=-1", http.StatusBadRequest},
+		{"/range/100?duration=XYZ", http.StatusBadRequest},
+		{"/range/100?duration=2h", http.StatusBadRequest},
 	}
 
 	for _, test := range badTests {

httpbin/helpers.go

@@ -314,17 +314,21 @@ func parseSeed(rawSeed string) (*rand.Rand, error) {
 type syntheticByteStream struct {
 	mu sync.Mutex
 
-	size    int64
-	offset  int64
-	factory func(int64) byte
+	size         int64
+	factory      func(int64) byte
+	pausePerByte time.Duration
+
+	// internal offset for tracking the current position in the stream
+	offset int64
 }
 
 // newSyntheticByteStream returns a new stream of bytes of a specific size,
 // given a factory function for generating the byte at a given offset.
-func newSyntheticByteStream(size int64, factory func(int64) byte) io.ReadSeeker {
+func newSyntheticByteStream(size int64, duration time.Duration, factory func(int64) byte) io.ReadSeeker {
 	return &syntheticByteStream{
-		size:    size,
-		factory: factory,
+		size:         size,
+		pausePerByte: duration / time.Duration(size),
+		factory:      factory,
 	}
 }
 
@@ -344,9 +348,12 @@ func (s *syntheticByteStream) Read(p []byte) (int, error) {
 	for idx := start; idx < end; idx++ {
 		p[idx-start] = s.factory(idx)
 	}
-
 	s.offset = end
 
+	if s.pausePerByte > 0 {
+		time.Sleep(s.pausePerByte * time.Duration(end-start))
+	}
+
 	return int(end - start), err
 }
 

httpbin/helpers_test.go

@@ -148,33 +148,39 @@ func TestSyntheticByteStream(t *testing.T) {
 
 	t.Run("read", func(t *testing.T) {
 		t.Parallel()
-		s := newSyntheticByteStream(10, factory)
+		s := newSyntheticByteStream(10, 0, factory)
 
 		// read first half
-		p := make([]byte, 5)
-		count, err := s.Read(p)
-		assert.NilError(t, err)
-		assert.Equal(t, count, 5, "incorrect number of bytes read")
-		assert.DeepEqual(t, p, []byte{0, 1, 2, 3, 4}, "incorrect bytes read")
+		{
+			p := make([]byte, 5)
+			count, err := s.Read(p)
+			assert.NilError(t, err)
+			assert.Equal(t, count, 5, "incorrect number of bytes read")
+			assert.DeepEqual(t, p, []byte{0, 1, 2, 3, 4}, "incorrect bytes read")
+		}
 
 		// read second half
-		p = make([]byte, 5)
-		count, err = s.Read(p)
-		assert.Error(t, err, io.EOF)
-		assert.Equal(t, count, 5, "incorrect number of bytes read")
-		assert.DeepEqual(t, p, []byte{5, 6, 7, 8, 9}, "incorrect bytes read")
+		{
+			p := make([]byte, 5)
+			count, err := s.Read(p)
+			assert.Error(t, err, io.EOF)
+			assert.Equal(t, count, 5, "incorrect number of bytes read")
+			assert.DeepEqual(t, p, []byte{5, 6, 7, 8, 9}, "incorrect bytes read")
+		}
 
 		// can't read any more
-		p = make([]byte, 5)
-		count, err = s.Read(p)
-		assert.Error(t, err, io.EOF)
-		assert.Equal(t, count, 0, "incorrect number of bytes read")
-		assert.DeepEqual(t, p, []byte{0, 0, 0, 0, 0}, "incorrect bytes read")
+		{
+			p := make([]byte, 5)
+			count, err := s.Read(p)
+			assert.Error(t, err, io.EOF)
+			assert.Equal(t, count, 0, "incorrect number of bytes read")
+			assert.DeepEqual(t, p, []byte{0, 0, 0, 0, 0}, "incorrect bytes read")
+		}
 	})
 
 	t.Run("read into too-large buffer", func(t *testing.T) {
 		t.Parallel()
-		s := newSyntheticByteStream(5, factory)
+		s := newSyntheticByteStream(5, 0, factory)
 		p := make([]byte, 10)
 		count, err := s.Read(p)
 		assert.Error(t, err, io.EOF)
@@ -184,7 +190,7 @@ func TestSyntheticByteStream(t *testing.T) {
 
 	t.Run("seek", func(t *testing.T) {
 		t.Parallel()
-		s := newSyntheticByteStream(100, factory)
+		s := newSyntheticByteStream(100, 0, factory)
 
 		p := make([]byte, 5)
 		s.Seek(10, io.SeekStart)
@@ -211,6 +217,52 @@ func TestSyntheticByteStream(t *testing.T) {
 		_, err = s.Seek(-10, io.SeekStart)
 		assert.Equal(t, err.Error(), "Seek: invalid offset", "incorrect error for invalid offset")
 	})
+
+	t.Run("read over duration", func(t *testing.T) {
+		t.Parallel()
+		s := newSyntheticByteStream(10, 200*time.Millisecond, factory)
+
+		// read first half
+		{
+			p := make([]byte, 5)
+			start := time.Now()
+			count, err := s.Read(p)
+			elapsed := time.Since(start)
+
+			assert.NilError(t, err)
+			assert.Equal(t, count, 5, "incorrect number of bytes read")
+			assert.DeepEqual(t, p, []byte{0, 1, 2, 3, 4}, "incorrect bytes read")
+			assert.DurationRange(t, elapsed, 100*time.Millisecond, 175*time.Millisecond)
+		}
+
+		// read second half
+		{
+			p := make([]byte, 5)
+			start := time.Now()
+			count, err := s.Read(p)
+			elapsed := time.Since(start)
+
+			assert.Error(t, err, io.EOF)
+			assert.Equal(t, count, 5, "incorrect number of bytes read")
+			assert.DeepEqual(t, p, []byte{5, 6, 7, 8, 9}, "incorrect bytes read")
+			assert.DurationRange(t, elapsed, 100*time.Millisecond, 175*time.Millisecond)
+		}
+
+		// can't read any more
+		{
+			p := make([]byte, 5)
+			start := time.Now()
+			count, err := s.Read(p)
+			elapsed := time.Since(start)
+
+			assert.Error(t, err, io.EOF)
+			assert.Equal(t, count, 0, "incorrect number of bytes read")
+			assert.DeepEqual(t, p, []byte{0, 0, 0, 0, 0}, "incorrect bytes read")
+
+			// read should fail w/ EOF ~immediately
+			assert.DurationRange(t, elapsed, 0, 25*time.Millisecond)
+		}
+	})
 }
 
 func TestGetClientIP(t *testing.T) {