Cargo.toml

[package]
name = "os-proxy-resolver"
version = "0.1.0"
edition = "2021"
rust-version = "1.77"
# All first-party code is MIT (see LICENSE.txt). The embedded PAC engine links
# the MIT-licensed quickjs-ng via the `rquickjs-sys` crate; the PAC helper
# functions are original, implemented from the public PAC specification.
license = "MIT"
description = "Resolve the OS-configured proxy (static, PAC, WPAD) for a URL, with change notification and a sandboxed PAC engine."
repository = "https://github.com/microsoft/os-proxy-resolver"
keywords = ["proxy", "pac", "wpad", "winhttp", "system-proxy"]
categories = ["network-programming", "os"]

[lib]
crate-type = ["rlib", "cdylib"]

[features]
# PAC backend selection is explicit: enable at least one of `pac-engine`
# (native QuickJS), `pac-engine-wasmtime` (sandboxed), or the other backends
# below. On non-Windows a backend is required (there is no OS PAC evaluator),
# so building with no features is a compile error. On Windows the default
# backend-less build delegates PAC/WPAD resolution to WinHTTP.
default = []
# Async change notification via tokio::sync::watch.
tokio = ["dep:tokio"]
# The embedded native QuickJS PAC engine (compiles the quickjs-ng C sources via
# `rquickjs-sys`). Optional on every platform and selected for normal PAC
# resolution when it is the configured backend.
pac-engine = ["dep:rquickjs-sys"]
# The sandboxed PAC backend: QuickJS-NG compiled to WebAssembly (see
# pac-wasm-guest/), run under Wasmtime in AOT mode. The runtime dependency is
# compiled WITHOUT any compiler (no Cranelift/JIT) — build.rs precompiles the
# vendored guest module with a build-dependency Wasmtime instead, and at
# runtime only `Module::deserialize` is used. Independent of `pac-engine`, so a
# Wasmtime-only build is possible; enable both to compare them (e.g. in
# `pac_bench`). Cannot target platforms Cranelift can't AOT-compile for (e.g.
# 32-bit armv7) — use `pac-engine-wasm2c` (sandboxed) or `pac-engine` (native)
# there instead.
pac-engine-wasmtime = ["dep:wasmtime"]
# The portable sandboxed PAC backend: the same wasm guest as
# `pac-engine-wasmtime`, but translated to standard C with WABT's `wasm2c` at
# build time and compiled like any other C code — which makes the wasm sandbox
# available on every target the crate compiles for, including ones Cranelift
# cannot AOT-compile for (32-bit armv7, ...). Requires the pinned `wasm2c`
# binary on the build host (see pac-wasm-guest/README.md). Slower than the
# Wasmtime backend (explicit bounds checks on every memory access) but with
# identical PAC semantics; independent of the other two backend features.
pac-engine-wasm2c = ["dep:cc"]
# JIT variant of the Wasmtime backend: the same guest and host code, but with
# Cranelift compiled into the runtime and the vendored pac_guest.wasm
# JIT-compiled at startup (`Module::new`) instead of AOT-precompiled by
# build.rs. The operationally simplest wasm backend — no build-time compile
# step, no target-specific artifact, no version-locked `unsafe` deserialize —
# at the cost of the largest binary (Cranelift ships in it), a one-time
# startup compile, and giving up the AOT build's "no compiler at runtime"
# hardening. Select it with `PacBackendKind::WasmtimeJit`; independent of the
# other backend features.
pac-engine-wasmtime-jit = ["dep:wasmtime", "wasmtime/cranelift"]

[dependencies]
url = "2"
log = "0.4"
tokio = { version = "1", optional = true, default-features = false, features = ["sync"] }
# Public Suffix List used to stop the WPAD suffix walk at the registrable domain.
psl = "2"

# Runtime for the sandboxed PAC backend, in AOT mode only: `runtime` + `std`
# but deliberately NO `cranelift` (or `winch`/`pulley`), so this build cannot
# compile wasm at all — it can only `Module::deserialize` the artifact that
# build.rs precompiled. Pinned to the exact version of the `wasmtime-aot`
# build-dependency below because serialized modules only deserialize in the
# same Wasmtime version. (The `pac-engine-wasmtime-jit` feature deliberately
# re-adds `cranelift` here.)
wasmtime = { version = "=46.0.1", optional = true, default-features = false, features = ["runtime", "std"] }

[build-dependencies]
# Compile-only Wasmtime (Cranelift, no runtime) used by build.rs to
# ahead-of-time compile pac-wasm-guest/pac_guest.wasm for $TARGET. Same crate,
# same pinned version as the runtime dependency above (serialized modules only
# deserialize in the identical Wasmtime version), but a different feature set:
# the feature resolver (v2) does not unify features between build- and normal
# dependencies, so Cranelift stays out of the library itself. `all-arch`
# compiles every Cranelift ISA into the build script, so cross-compiling the
# crate (macOS -> Windows, x86_64 container -> aarch64/armv7, ...) can still
# AOT the guest for the *target* architecture.
wasmtime = { version = "=46.0.1", optional = true, default-features = false, features = ["cranelift", "std", "all-arch"] }
# Compiles the wasm2c-generated C, the vendored wasm-rt runtime and the C shim
# for the `pac-engine-wasm2c` backend.
cc = { version = "1", optional = true }

[target.'cfg(not(windows))'.dependencies]
# PAC / wpad.dat fetching. Sync and rustls-backed, loading roots from the OS
# trust store so locally installed enterprise CAs are honored.
ureq = { version = "2", default-features = false, features = ["tls", "native-certs", "gzip"] }
# Embedded QuickJS-NG (MIT) for the native PAC engine. Vendors and compiles the
# quickjs-ng C sources via `cc`. Optional (feature `pac-engine`) so a
# Wasmtime-only build links no C engine.
rquickjs-sys = { version = "0.12.1", optional = true }

[target.'cfg(target_os = "macos")'.dependencies]
core-foundation = "0.9"
system-configuration = "0.6"

[target.'cfg(windows)'.dependencies]
windows-sys = { version = "0.60", features = [
    "Win32_Foundation",
    "Win32_NetworkManagement_IpHelper",
    "Win32_NetworkManagement_Ndis",
    "Win32_Networking_WinHttp",
    "Win32_Networking_WinSock",
    "Win32_Security",
    "Win32_System_Registry",
    "Win32_System_Threading",
] }
# Optional on Windows and enabled by the `pac-engine` feature, matching the
# non-Windows dependency above.
rquickjs-sys = { version = "0.12.1", optional = true }

[target.'cfg(target_os = "linux")'.dependencies]
libc = "0.2"

[dev-dependencies]
tokio = { version = "1", features = ["sync", "rt", "macros", "time"] }

[profile.release]
# The wasm2c backend generates one C function per wasm function (~53k for the
# QuickJS guest). Their local symbols would otherwise add several MiB of symbol
# table to release binaries — most visibly on macOS, whose linker keeps all
# local symbols, where it roughly triples the wasm2c size delta. Stripping
# removes them (no runtime effect) and keeps artifact sizes comparable across
# platforms.
strip = "symbols"