implement the purge API

Currently this only supports surrogate key purging.

Author: joeshaw

_examples/corecache/main.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/fastly/compute-sdk-go/cache/core"
 	"github.com/fastly/compute-sdk-go/fsthttp"
+	"github.com/fastly/compute-sdk-go/purge"
 )
 
 func main() {
@@ -115,8 +116,11 @@ func main() {
 
 		// Purge the key from the cache.
 		case "DELETE":
-			// TODO: purge the surrogate key.
-			w.WriteHeader(fsthttp.StatusNotImplemented)
+			if err := purge.PurgeSurrogateKey(hex.EncodeToString(key), purge.PurgeOptions{}); err != nil {
+				fsthttp.Error(w, err.Error(), fsthttp.StatusInternalServerError)
+				return
+			}
+			w.WriteHeader(fsthttp.StatusAccepted)
 
 		default:
 			w.WriteHeader(fsthttp.StatusMethodNotAllowed)

internal/abi/fastly/hostcalls_guest.go

@@ -2908,3 +2908,38 @@ func (c *CacheEntry) Hits() (uint64, error) {
 
 	return uint64(d), nil
 }
+
+type PurgeOptions struct {
+	mask purgeOptionsMask
+	opts purgeOptions
+}
+
+func (o *PurgeOptions) SoftPurge(v bool) {
+	if v {
+		o.mask |= purgeOptionsMaskSoftPurge
+	} else {
+		o.mask &^= purgeOptionsMaskSoftPurge
+	}
+}
+
+// witx:
+//
+//	(@interface func (export "purge_surrogate_key")
+//	    (param $surrogate_key string)
+//	    (param $options_mask $purge_options_mask)
+//	    (param $options (@witx pointer $purge_options))
+//	    (result $err (expected (error $fastly_status)))
+//	)
+//
+//go:wasm-module fastly_purge
+//export purge_surrogate_key
+//go:noescape
+func fastlyPurgeSurrogateKey(surrogateKey prim.Wstring, mask purgeOptionsMask, opts *purgeOptions) FastlyStatus
+
+func PurgeSurrogateKey(surrogateKey string, opts PurgeOptions) error {
+	return fastlyPurgeSurrogateKey(
+		prim.NewReadBufferFromString(surrogateKey).Wstring(),
+		opts.mask,
+		&opts.opts,
+	).toError()
+}

internal/abi/fastly/hostcalls_noguest.go

@@ -399,3 +399,13 @@ func (c *CacheEntry) Age() (time.Duration, error) {
 func (c *CacheEntry) Hits() (uint64, error) {
 	return 0, fmt.Errorf("not implemented")
 }
+
+type PurgeOptions struct{}
+
+func (o *PurgeOptions) SoftPurge(v bool) error {
+	return fmt.Errorf("not implemented")
+}
+
+func PurgeSurrogateKey(surrogateKey string, opts PurgeOptions) error {
+	return fmt.Errorf("not implemented")
+}

internal/abi/fastly/types.go

@@ -639,3 +639,34 @@ const (
 	CacheLookupStateStale              CacheLookupState = 0b0000_0100 // $stale
 	CacheLookupStateMustInsertOrUpdate CacheLookupState = 0b0000_1000 // $must_insert_or_update
 )
+
+// witx:
+//
+//	(typename $purge_options_mask
+//	    (flags (@witx repr u32)
+//	        $soft_purge
+//	        $ret_buf ;; all ret_buf fields must be populated
+//	    )
+//	)
+type purgeOptionsMask prim.U32
+
+const (
+	purgeOptionsMaskSoftPurge purgeOptionsMask = 1 << 0 // $soft_purge
+	purgeOptionsMaskRetBuf    purgeOptionsMask = 1 << 1 // $ret_buf
+)
+
+// witx:
+//
+//	(typename $purge_options
+//	    (record
+//	        ;; JSON purge response as in https://developer.fastly.com/reference/api/purging/#purge-tag
+//	        (field $ret_buf_ptr (@witx pointer u8))
+//	        (field $ret_buf_len (@witx usize))
+//	        (field $ret_buf_nwritten_out (@witx pointer (@witx usize)))
+//	    )
+//	)
+type purgeOptions struct {
+	retBufPtr         *prim.U8
+	retBufLen         prim.Usize
+	retBufNwrittenOut *prim.Usize
+}

purge/purge.go

@@ -0,0 +1,25 @@
+// Package purge provides cache purging operations for Fastly
+// Compute@Edge.
+//
+// See the [Fastly purge documentation] for details.
+//
+// [Fastly purge documentation]: https://developer.fastly.com/learning/concepts/purging/
+package purge
+
+import "github.com/fastly/compute-sdk-go/internal/abi/fastly"
+
+// PurgeOptions control the behavior of purge operations.
+type PurgeOptions struct {
+	// Whether to soft purge the item.  A soft purge marks a cached
+	// object as stale, rather than invalidating it.
+	Soft bool
+}
+
+// PurgeSurrogateKey purges all cached objects with the provided
+// surrogate key.
+func PurgeSurrogateKey(surrogateKey string, opts PurgeOptions) error {
+	var abiOpts fastly.PurgeOptions
+	abiOpts.SoftPurge(opts.Soft)
+
+	return fastly.PurgeSurrogateKey(surrogateKey, abiOpts)
+}