Add Geo Lookup Support

Bắt đầu với WIT binding tại stubs/wit_world/imports/geo.py và so sánh Python API được yêu cầu với các tham chiếu Rust, Go và JS trong issue. Sử dụng cấu hình định vị test.toml của Viceroy và các test @on_viceroy để kiểm thử các địa chỉ loopback và các địa chỉ đã cấu hình. Được xem là hoàn tất khi lookup API, biểu diễn response có kiểu, hành vi khi thất bại và độ bao phủ của Viceroy khớp với thiết kế đã nêu.

Overview

Add support for Fastly's geographic and network intelligence API, which provides location and network information based on IP addresses.

WIT Interface

interface geo {
  use types.{error, ip-address};

  /// Returns JSON-encoded geographic data for an IP address
  lookup: func(ip-addr: ip-address, max-len: u64) -> result<string, error>;
}

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

API Design

• Parse JSON response from WIT layer into a Geo dataclass with typed fields (city, country, coordinates, AS number, etc.)
• Provide lookup(ip) function accepting str, IPv4Address, or IPv6Address
• Return None for failed lookups (e.g., private IPs without configuration)
• Optional: convenience lookup_client(request) helper

Cross-SDK Comparison:

• Rust (fastly::geo::geo_lookup): Returns strongly-typed Geo struct with enums for ConnSpeed, ConnType, Continent, ProxyDescription, ProxyType. Uses Option<UtcOffset> from time crate. All string/enum fields have Other(String) variant for forward-compatibility. Returns Option<Geo> for missing data.

• Go (geo.Lookup): Returns *Geo struct with all string fields (no enums). Returns pointer to empty struct when no data available. Uses raw int for UTCOffset (HHMM format like 200 or -500).

• JS (getGeolocationForIpAddress): Returns Geolocation interface with all fields as T | null. Uses strings for enums. Has both utc_offset (number) and gmt_offset (string). Returns null for no data.

Recommended Python approach:

• Use @dataclass with typed fields for known attributes
• Include _extra: dict field (with repr=False) to capture unknown JSON fields
• Python Enum types for categorical fields (e.g., ConnType, Continent) using _missing_() to gracefully handle unknown values that might be added in future
• Use Optional[X] (equivalent) for truly optional fields (region, utc_offset)
• Return Geo | None from lookup() (align with Rust)
• Consider utc_offset as Optional[datetime.timedelta] for Pythonic time handling
• Match functionality from other SDKs for empty string values.

Forward Compatibility Pattern:

from dataclasses import dataclass, field

@dataclass
class Geo:
    city: str
    country_code: str
    latitude: float
    longitude: float
    # ... other known fields
    _extra: dict = field(default_factory=dict, repr=False)
    
    @classmethod
    def from_json(cls, data: dict):
        known_fields = {'city', 'country_code', 'latitude', 'longitude', ...}
        known = {k: v for k, v in data.items() if k in known_fields}
        extra = {k: v for k, v in data.items() if k not in known_fields}
        return cls(**known, _extra=extra)
    
    def __getattr__(self, name):
        if name in self._extra:
            return self._extra[name]
        raise AttributeError(f"no attribute '{name}'")

# Benefits: Type hints for known fields, future fields accessible via attributes
geo = Geo.from_json(json_data)
print(geo.city)      # Type-checked by IDE
print(geo.timezone)  # Works if Fastly adds this field later

Viceroy Testing

Viceroy supports geo lookups with configurable test data via test.toml:

[local_server.geolocation]
format = "inline-toml"
use_default_loopback = true  # Returns default data for 127.0.0.1

[local_server.geolocation.addresses."203.0.113.42"]
city = "San Francisco"
country_code = "US"
latitude = 37.77869
# ... additional fields

Default loopback data is available without configuration. Tests can use @on_viceroy with inline TOML config or JSON file references.

Reference

• Fastly Geo Documentation