Struct PacPolicy 

pub struct PacPolicy { /* private fields */ }

Available on crate feature pac only.

Safety envelope for PAC evaluation (pac-boa; ignored by WinHttpPacResolver).

Defaults: no DNS, drop internal answers, myIpAddress() → 127.0.0.1, 5 s timeout, boa’s own recursion/stack limits, and a loop cap boa does not impose at all. Heap unbounded — OS-sourced PAC + DNS = high severity.

One default is not a limit: the crate reads no time zone, so local_utc_offset is 0 and weekdayRange, dateRange and timeRange answer in GMT whether or not the script passed "GMT" — a browser reads the host’s zone there. with_local_utc_offset is the only way to move them, and a fixed offset does not follow DST.

Every limit on this type is a VM limit: it bounds a script that is already running, and none of them bounds parsing. boa_parser 0.21.1 is a recursive-descent parser with no depth limit of its own, so nesting alone overflows the native stack before evaluation starts — measured through this type on the thread BoaEvaluator spawns for a script (x86-64 Windows, the stack std::thread gives a spawn by default): an optimized build parses 99 nested ( and aborts on 100, in a 256-byte script; the same source unoptimized aborts on 17. A native stack overflow aborts the process rather than panicking, so neither the dedicated evaluation thread nor the timeout contains it. A caller that accepts a PAC body it does not control has to isolate the process itself; no setting here substitutes for that.

Neither figure is a ceiling to design against. ( is the shape they were taken on, not the only one that recurses — [ and {a: overflow too, and unoptimized they do it at a comparable depth — so a screen written for ( screens (. And with with_timeout(None) there is no spawned thread to measure at all: the script parses on the calling thread, under whatever stack that thread was given. Upstream has the bug open (boa#4397) and closed the parser guard written for it (boa#4772) unmerged over the Test262 conformance it cost; 0.22.0 ships with none, so raising the dependency is not the way out either.

The script arrives over the network, which is why the defaults are what they are: standalone PAC libraries have been broken exactly there — pac-resolver escaped its Node.js vm and reached RCE (CVE-2021-23406) and pacparser had CVE-2023-37360.

Implementations

impl PacPolicy

pub fn new() -> Self

The default policy: no DNS, no internal addresses, no real local IP, 5 s budget.

pub fn with_dns_resolution(self, enabled: bool) -> Self

Allow dnsResolve, isResolvable and isInNet to perform name resolution.

With the default false, dnsResolve returns null and no DNS query is made.

pub fn with_internal_addresses(self, allowed: bool) -> Self

Allow answers in internal space (loopback, RFC 1918, link-local, CGNAT, … and the IPv4-mapped spelling of those). Default false drops them.

Classic dnsResolve is IPv4-only, so a native IPv6 answer — a ULA, say — never reaches this flag either way. IP literals in the script are never filtered.

pub fn with_my_ip_address(self, address: IpAddr) -> Self

Set the address myIpAddress() reports. Unset → 127.0.0.1 (no auto-discovery).

pub fn with_timeout(self, timeout: Option<Duration>) -> Self

Wall-clock budget, or None to remove it (blocks the caller if the script hangs).

Some(Duration::ZERO) is a budget of nothing, not the absence of one: every evaluation answers Error::PacTimeout. None is how a caller asks for no limit. WinHttpPacResolver::with_timeout answers zero the same way — it is named in backticks rather than linked because that type exists only under pac-windows-native on Windows, and a link to it fails the doc build everywhere else.

The budget bounds the call, not the script. On expiry BoaEvaluator returns Error::PacTimeout and abandons the evaluation thread, which runs on until one of the VM limits stops it — so that thread, and whatever it has allocated by then, outlives the call that asked for it. Nothing here interrupts a running script: bounding the work is what the limits below are for.

Read that per call and it sounds like untidiness; the cost is in the aggregate. Abandoned threads do not queue behind each other, so an application resolving repeatedly against a script that always overruns holds roughly overrun ÷ timeout of them at once, each spinning a core until its own VM limit lands. With the defaults that ratio is not small: a while (true) {} reaches DEFAULT_PAC_LOOP_LIMIT in about 93 seconds on an unoptimized build of this crate, against a budget of DEFAULT_PAC_TIMEOUT. Shortening the budget widens the ratio rather than narrowing it. What bounds this is a lower PacPolicy::with_max_loop_iterations, or not letting the calls stack up.

pub fn with_max_loop_iterations(self, limit: u64) -> Self

Loop-iteration cap (u64::MAX disables). Honoured via boa_engine RuntimeLimits.

Iterations, not allocations — the same distinction DEFAULT_PAC_STACK_SIZE_LIMIT draws. The limit is checked where the engine re-enters a loop body, so whatever a builtin allocates within a call it never reaches: a script that spends its memory in one String.prototype.repeat rather than in a loop has nothing stopping it — the cap never fires, and PacPolicy::with_timeout ends the wait rather than the work. That is the gap the type doc’s “Heap unbounded” names.

pub fn with_recursion_limit(self, limit: usize) -> Self

Recursion depth cap. Default DEFAULT_PAC_RECURSION_LIMIT is boa’s own.

pub fn with_stack_size_limit(self, limit: usize) -> Self

Value-stack entry cap (not bytes / OS stack). Default DEFAULT_PAC_STACK_SIZE_LIMIT.

pub fn with_local_utc_offset(self, seconds: i32) -> Self

Seconds from UTC treated as “local” for date/time predicates (default 0 = GMT).

pub fn with_now(self, now: SystemTime) -> Self

Pin the clock the time-dependent host functions see.

Intended for tests and for reproducing a routing decision after the fact.

pub fn resolve_dns(&self) -> bool

Whether name resolution is permitted.

pub fn allow_internal_addresses(&self) -> bool

Whether resolution results in internal address space are kept.

pub fn my_ip_address(&self) -> IpAddr

The address myIpAddress() reports, or 127.0.0.1 when unset.

pub fn timeout(&self) -> Option<Duration>

The wall-clock evaluation budget.

pub fn max_loop_iterations(&self) -> u64

The loop iteration cap.

pub fn recursion_limit(&self) -> usize

The function-call recursion depth cap.

pub fn stack_size_limit(&self) -> usize

The cap on the engine’s internal value-stack length.

pub fn local_utc_offset(&self) -> i32

The offset from UTC, in seconds, that counts as local time.

pub fn now(&self) -> Option<SystemTime>

The pinned clock, when with_now was used.

Trait Implementations

impl Clone for PacPolicy

fn clone(&self) -> PacPolicy

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for PacPolicy

impl Debug for PacPolicy

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PacPolicy

fn default() -> Self

Returns the “default value” for a type.

impl Eq for PacPolicy

impl PartialEq for PacPolicy

fn eq(&self, other: &PacPolicy) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for PacPolicy