Add Cache Purge Support

[posborne]

Overview

Add support for Fastly's Cache Purge API, enabling surrogate key-based cache invalidation.

WIT Interface

interface purge {
  use types.{error};

  resource extra-purge-options;

  record purge-options {
    soft-purge: bool,
    extra: option<borrow<extra-purge-options>>,
  }

  purge-surrogate-key: func(surrogate-keys: string, purge-options: purge-options) -> result<_, error>;
  purge-surrogate-key-verbose: func(surrogate-keys: string, purge-options: purge-options, max-len: u64) -> result<string, error>;
}

WIT bindings: stubs/wit_world/imports/purge.py

API Design

• Simple function-based API: purge_surrogate_key(keys, soft=False)
• Optional verbose version: purge_surrogate_key_verbose(keys, soft=False) returns purge ID
• PurgeOptions dataclass with soft_purge boolean flag
• Support single or space-separated multiple surrogate keys (max 1024 chars per key)
• Return purge ID (JSON response) for verbose variant

Cross-SDK Comparison: All SDKs expose simple function-based API: purge_surrogate_key(key). Straightforward across all languages with similar semantics.

Viceroy Testing

Cache purge operations in Viceroy are likely stubbed or no-op. Tests should focus on:

• API wrapper behavior (parameter validation, error handling)
• Response parsing for verbose variant
• Use xfail markers for functionality requiring actual purge execution

The purge API primarily validates input and returns success without actually purging in local testing.

Reference

• Fastly Cache Purging Documentation
• Purge API Reference