Add HTTP Downstream Metadata API

[posborne]

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 #9: Issue #9 covers the low-level Request/Response wrappers. This issue (#14) 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 #9'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 #9):

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