Add Cache Purge Support

Bắt đầu với stubs/wit_world/imports/purge.py và tài liệu Fastly Cache Purging. Định nghĩa purge API dựa trên hàm và hành vi của PurgeOptions được mô tả trong issue, bao gồm việc xác thực và phân tích chi tiết phản hồi, sau đó thêm các bài kiểm thử wrapper cho những trường hợp đó cùng với độ bao phủ xfail cho các chức năng yêu cầu thực thi purge thực tế.

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