Option to respect range during cache streaming

The core cache API allows for cache items to be concurrently streamed to / from the cache.

If:
- The size of the cached item's body was not provided by the writer
- The reader requests a specific range of the cached item's body (`to_stream_from_range`)
- The writer and reader are concurrent, i.e. the body is streamed from one to the other

then today, the core cache API will ignore the requested range and provide the whole body. There is no explicit notification that the whole body is provided instead of a range.

In this SDK release, this remains the default behavior. However, the lookup options struct now now offers an `AlwaysUseRequestedRange` option. If set to true, body reads conducted as part of this lookup/transaction will always use the requested range, even when streaming. If false, the behavior is unchanged (as above).

In a future SDK release, the default behavior will change to
"always use requested range".

Author: cceckman-at-fastly

cache/core/core.go

@@ -258,6 +258,16 @@ type LookupOptions struct {
 	// To indicates the ending offset to read from the cached object.  A
 	// value of 0 means to read to the end of the object.
 	To uint64
+
+	// By default, if:
+	// - The size of the cached item's body was not provided by the writer
+	// - The reader requests a specific range of the cached item's body (`From` and `To` are set)
+	// - The writer and reader are concurrent, i.e. the body is streamed from one to the other
+	// then today, the core cache API will ignore the requested range and provide the whole body.
+	//
+	// Setting this flag provides the more intuitive behavior: the range will be respected
+	// during streaming as well.
+	AlwaysUseRequestedRange bool
 }
 
 func abiLookupOptions(opts LookupOptions) (fastly.CacheLookupOptions, error) {
@@ -272,6 +282,8 @@ func abiLookupOptions(opts LookupOptions) (fastly.CacheLookupOptions, error) {
 		abiOpts.SetRequest(req)
 	}
 
+	abiOpts.SetAlwaysUseRequestedRange(opts.AlwaysUseRequestedRange)
+
 	return abiOpts, nil
 }
 

cache/core/core_test.go

@@ -208,3 +208,46 @@ func ExampleFound_GetRange() {
 
 	fmt.Printf("The cached value was: %s", cachedStr)
 }
+
+func ExampleLookupOptions_AlwaysUseRequestedRange() {
+	const (
+		key      = "my_key"
+		contents = "my cached object"
+	)
+
+	// Start an insert; this will be concurrent with the read.
+	// Data written to this handle is streamed into the Fastly cache.
+	w, err := core.Insert([]byte(key), core.WriteOptions{
+		TTL:           time.Hour,
+		SurrogateKeys: []string{key},
+		Length:        uint64(len(contents)),
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	// With the write still outstanding, start a lookup for a specific range.
+	f, err := core.Lookup([]byte("my_key"), core.LookupOptions{
+		From:                    3,
+		To:                      8,
+		AlwaysUseRequestedRange: true,
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	// Write and flush:
+	if _, err := io.WriteString(w, contents); err != nil {
+		panic(err)
+	}
+
+	cachedStr, err := io.ReadAll(f.Body)
+	if err != nil {
+		panic(err)
+	}
+	if string(cachedStr) != "cached" {
+		panic(fmt.Sprintf("got: %q, want: %q", cachedStr, "cached object"))
+	}
+
+	fmt.Printf("The cached value was: %s", cachedStr)
+}

internal/abi/fastly/cache_guest.go

@@ -21,6 +21,14 @@ func (o *CacheLookupOptions) SetRequest(req *HTTPRequest) {
 	o.mask |= cacheLookupOptionsMaskRequestHeaders
 }
 
+func (o *CacheLookupOptions) SetAlwaysUseRequestedRange(alwaysUseRequestedRange bool) {
+	if alwaysUseRequestedRange {
+		o.mask |= cacheLookupOptionsMaskAlwaysUseRequestedRange
+	} else {
+		o.mask &= ^cacheLookupOptionsMaskAlwaysUseRequestedRange
+	}
+}
+
 type CacheGetBodyOptions struct {
 	opts cacheGetBodyOptions
 	mask cacheGetBodyOptionsMask

internal/abi/fastly/hostcalls_noguest.go

@@ -425,6 +425,10 @@ func (o *CacheLookupOptions) SetRequest(req *HTTPRequest) error {
 	return fmt.Errorf("not implemented")
 }
 
+func (o *CacheLookupOptions) SetAlwaysUseRequestedRange(alwaysUseRequestedRange bool) error {
+	return fmt.Errorf("not implemented")
+}
+
 func (o *CacheGetBodyOptions) From(from uint64) error {
 	return fmt.Errorf("not implemented")
 }

internal/abi/fastly/types.go

@@ -721,13 +721,16 @@ type cacheLookupOptions struct {
 //	    (flags (@witx repr u32)
 //	        $reserved
 //	        $request_headers
+//	        $service_id
+//	        $always_use_requested_range
 //	    )
 //	)
 type cacheLookupOptionsMask prim.U32
 
 const (
-	cacheLookupOptionsMaskReserved       cacheLookupOptionsMask = 0b0000_0001 // $reserved
-	cacheLookupOptionsMaskRequestHeaders cacheLookupOptionsMask = 0b0000_0010 // $request_headers
+	cacheLookupOptionsMaskReserved                cacheLookupOptionsMask = 0b0000_0001 // $reserved
+	cacheLookupOptionsMaskRequestHeaders          cacheLookupOptionsMask = 0b0000_0010 // $request_headers
+	cacheLookupOptionsMaskAlwaysUseRequestedRange cacheLookupOptionsMask = 0b0000_1000 // $always_use_requested_range
 )
 
 // witx: