Module types 

Core domain types for proxy management.

IP class and target compatibility

The 2026 scraping guide (see docs/dev/project/scraping-guide-2026-llm-context.md §“PROXY PROVIDERS AND TYPES”) ranks egress IPs into a four-tier trust hierarchy used by every Tier-1 anti-bot vendor:

Rank	IpClass	Typical use
4	Mobile	3G/4G/5G carrier egress — defeats DataDome, PerimeterX, Kasada
3	Isp	Static/ISP allocation — defeats Akamai, Cloudflare, PerimeterX
2	Residential	Rotating residential pool — defeats most Tier-1 vendors
1	Datacenter	Hosted VPS / bare-metal — defeated by DataDome, PerimeterX
0	Unknown	Provider did not tag the egress — fail-secure default

Each Proxy and ProxyCapabilities carries two typed fields that drive capability-aware acquisition:

• ip_class: IpClass — the proxy’s egress tier. Acquisition matches via ip_class.rank() >= requirement.rank() so a Mobile proxy satisfies a request that requires Isp.
• target_compatibility: TargetVendorCompatibility — a BTreeMap<VendorId, TrustTier> mapping each anti-bot vendor to a declared effectiveness tier. Free-list fetchers tag every ingested proxy as default_blocked() (no vendor confirmed) so callers cannot accidentally route premium traffic through a public free-list pool.

Geo enrichment

Operators targeting specific cities / ASNs / postal codes — the “Infatica-style city, ZIP, and ASN” filter cited by the 2026 scraping guide (L2837) — populate the optional asn, city, and postal_code fields on ProxyCapabilities. The corresponding require_asn, require_city, and require_postal_code fields on CapabilityRequirement select proxies whose geo metadata matches. Empty requirement still matches any proxy (the existing invariant is preserved).

use stygian_proxy::types::{CapabilityRequirement, ProxyCapabilities};
use stygian_proxy::types::well_known::KNOWN_ASN_CLOUDFLARE;

// Akamai scrape: insist the egress IP is in Cloudflare's AS.
let caps = ProxyCapabilities {
    asn: Some(KNOWN_ASN_CLOUDFLARE),
    city: Some("San Francisco".into()),
    postal_code: Some("94110".into()),
    ..Default::default()
};
let req = CapabilityRequirement {
    require_asn: Some(KNOWN_ASN_CLOUDFLARE),
    require_city: Some("San Francisco".into()),
    require_postal_code: Some("94110".into()),
    ..Default::default()
};
assert!(caps.satisfies(&req));

use stygian_proxy::types::{IpClass, TargetVendorCompatibility, TrustTier, VendorId};

// A static-ISP proxy confirmed effective against Akamai and Cloudflare.
let compat = TargetVendorCompatibility::default()
    .set(VendorId::Akamai, TrustTier::Preferred)
    .set(VendorId::Cloudflare, TrustTier::Acceptable);
assert_eq!(compat.get(VendorId::Akamai), Some(TrustTier::Preferred));
assert_eq!(IpClass::Isp.rank(), 3);

Modules

well_known

Canonical ASN values for major public CDNs and infrastructure providers.

Structs

CapabilityRequirement

Required capability set used as a filter when acquiring a proxy.

IpClassRequirement

Minimum IpClass required for a capability-aware acquisition.

Proxy

A proxy endpoint with optional authentication credentials.

ProxyCapabilities

Protocol-level capabilities advertised by a proxy endpoint.

ProxyConfig

Configuration governing health checking and circuit-breaker behaviour.

ProxyMetrics

Per-proxy runtime metrics using lock-free atomic counters.

ProxyRecord

A Proxy with a stable identity and insertion timestamp.

TargetVendorCompatibility

Mapping from anti-bot VendorId to the proxy’s declared TrustTier against that vendor.

Enums

IpClass

IP trust class for a proxy egress.

ProfiledRequestMode

TLS-profiled request mode for proxy-side HTTP operations.

ProxyType

The protocol variant of a proxy endpoint.

RoutingPath

The protocol routing path resolved for an outbound request.

TrustTier

Declared effectiveness of a proxy against a given anti-bot vendor.

VendorId

Anti-bot vendor identifier.

Constants

CITY_MAX_LEN

Maximum length of an operator-supplied city string.

POSTAL_CODE_MAX_LEN

Maximum length of an operator-supplied postal_code string.

Functions

validate_asn

Returns Ok(()) when asn is a valid public Autonomous System Number, otherwise an crate::error::ProxyError::InvalidGeoMetadata describing the failure.

validate_city

Returns Ok(()) when city is a valid operator-supplied city label, otherwise an crate::error::ProxyError::InvalidGeoMetadata.

validate_postal_code

Returns Ok(()) when postal_code is a valid operator-supplied postal / ZIP code, otherwise an crate::error::ProxyError::InvalidGeoMetadata.