Add HTTP Downstream Metadata API

stubs/wit_world/imports/http_downstream.py から始め、そのインターフェースを issue #009 で予定されている Request wrapper と比較します。src/component/compute/http_downstream.rs と Viceroy のテストノートを確認し、サポートされているメタデータと、stub 化された TLS および fingerprint 関数を切り分けます。完了条件は、合意された downstream API を公開し、サポート対象の動作、複数リクエストの処理、および文書化された Viceroy の制限をカバーすることです。

Overview

Add support for accessing downstream (incoming) HTTP request metadata, including client/server IP addresses, TLS connection details, security fingerprints, and compliance information.

Relationship to Issue #009: Issue #009 covers the low-level Request/Response wrappers. This issue (#014) specifically focuses on implementing the downstream metadata functions from the http-downstream WIT interface. These functions take a Request and return metadata, and will likely be exposed via a request.downstream accessor as shown in #009's examples.

WIT Interface

interface http-downstream {
  use http-req.{request, client-cert-verify-result};
  use types.{ip-address, error};
  use http-body.body;
  use async-io.pollable;

  // Multi-request handling
  next-request: func(options: next-request-options) -> result<pending-request, error>;
  await-request: func(pending: pending-request) -> result<option<tuple<request, body>>, error>;

  // IP addresses
  downstream-client-ip-addr: func(ds-request: request) -> option<ip-address>;
  downstream-server-ip-addr: func(ds-request: request) -> option<ip-address>;

  // TLS metadata
  downstream-tls-cipher-openssl-name: func(ds-request: request, max-len: u64) -> result<option<list<u8>>, error>;
  downstream-tls-protocol: func(ds-request: request, max-len: u64) -> result<option<list<u8>>, error>;
  downstream-tls-client-hello: func(ds-request: request, max-len: u64) -> result<option<list<u8>>, error>;
  downstream-tls-raw-client-certificate: func(ds-request: request, max-len: u64) -> result<option<list<u8>>, error>;
  downstream-tls-client-cert-verify-result: func(ds-request: request) -> result<option<client-cert-verify-result>, error>;
  downstream-tls-client-servername: func(ds-request: request, max-len: u64) -> result<option<string>, error>;
  downstream-tls-ja3-md5: func(ds-request: request) -> result<option<list<u8>>, error>;
  downstream-tls-ja4: func(ds-request: request, max-len: u64) -> result<option<string>, error>;

  // Security and fingerprinting
  downstream-client-h2-fingerprint: func(ds-request: request, max-len: u64) -> result<string, error>;
  downstream-client-oh-fingerprint: func(ds-request: request, max-len: u64) -> result<string, error>;
  downstream-client-ddos-detected: func(ds-request: request) -> result<bool, error>;
  downstream-client-request-id: func(ds-request: request, max-len: u64) -> result<string, error>;

  // Compliance and headers
  downstream-compliance-region: func(ds-request: request, max-len: u64) -> result<option<string>, error>;
  downstream-original-header-names: func(ds-request: request, max-len: u64, cursor: u32) -> result<tuple<string, option<u32>>, error>;
  downstream-original-header-count: func(ds-request: request) -> result<u32, error>;

  // Purge authentication
  fastly-key-is-valid: func(ds-request: request) -> result<bool, error>;
}

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

API Design

Functions that take a Request and return metadata (likely exposed via request.downstream accessor):

• IP Access: get_client_ip(request) / get_server_ip(request) returning Optional[Union[IPv4Address, IPv6Address]]
• TLS Info: get_tls_cipher(request), get_tls_protocol(request), get_tls_ja3_md5(request), get_tls_ja4(request)
• Client Certificates: get_client_certificate(request), get_client_cert_verify_result(request)
• Security: is_ddos_detected(request), get_request_id(request), get_h2_fingerprint(request)
• Compliance: get_compliance_region(request) for GDPR/data residency
• Headers: get_original_headers(request) preserving case and order
• Multi-request: next_request(timeout_ms) / await_request(pending) for handling multiple requests per sandbox

Usage via Request wrapper (see issue #009):

client_ip = incoming_req.downstream.client_ip()
tls_ja3 = incoming_req.downstream.tls_ja3_md5()

Cross-SDK Comparison: Rust exposes these as methods on Request extensions, Go uses functions in fsthttp package, JS provides via event.client object. Python will likely expose via request.downstream namespace for clean API.

Viceroy Testing

Viceroy implementation status (src/component/compute/http_downstream.rs):

✅ Fully Supported:

• downstream_client_ip_addr - Returns client IP from request context
• downstream_server_ip_addr - Returns server IP from request context
• downstream_original_header_names / downstream_original_header_count - Preserves original header casing/order
• downstream_client_request_id - Returns generated request ID (format: 32-char hex)
• downstream_compliance_region - Returns compliance region if configured
• next_request / await_request - Multi-request handling works

⚠️ Stubbed (returns None/empty):

• All downstream_tls_* functions - Return None (no TLS metadata in local testing)
• downstream_client_h2_fingerprint - Returns empty string
• downstream_client_oh_fingerprint - Returns empty string
• downstream_client_ddos_detected - Always returns false
• fastly_key_is_valid - Always returns false

Testing Approach:

• Use @on_viceroy with inline TOML for IP address configuration
• Mark TLS/fingerprint tests as xfail - they return None in Viceroy
• Test multi-request handling with sequential request pattern
• Test original header preservation with mixed-case headers

Example test config:

[local_server]
client_ip = "203.0.113.42"
compliance_region = "EU"

Reference

• Fastly Compute Request Documentation
• Client IP Detection
• TLS Variables