Add Cache Purge Support

Start with stubs/wit_world/imports/purge.py and the Fastly Cache Purging documentation. Define the function-based purge API and PurgeOptions behavior described in the issue, including validation and verbose response parsing, then add wrapper tests for those cases and xfail coverage for functionality requiring actual purge execution.

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