Struct PacEnv 

pub struct PacEnv { /* private fields */ }

Available on crate features js and pac and std only.

Builds the PAC javascript environment.

Registering it on a JsRuntimeBuilder adds every standard PAC host function, including Microsoft’s IPv6-aware extensions. Chromium defines that set except for getClientVersion; rama supports the full Microsoft surface.

Implementations

impl PacEnv

pub const DEFAULT_DNS_TIMEOUT: Duration

Default per-lookup timeout for the dns host functions.

pub const DEFAULT_MAX_LOOKUPS_PER_EVALUATION: u32 = 64

Default number of dns lookups one evaluation may make.

Generous for any real policy — reference scripts resolve the request host and little else — while keeping a hostile script from turning one request into an unbounded burst of queries.

pub const DEFAULT_MAX_GLOB_STEPS_PER_EVALUATION: u64 = 50_000_000

Default number of character comparisons shExpMatch may spend in one evaluation, across every call it makes.

Glob matching is native work no deadline can interrupt, so it needs a bound of its own. Far above what a real policy spends — a rule set testing a url costs thousands of steps, not millions — and exhausting it fails the evaluation rather than answering false, so a padded url cannot quietly stop a rule from matching.

pub const DEFAULT_MAX_ALERTS_PER_EVALUATION: u32 = 32

Default number of alert calls one evaluation may write to the log.

Diagnostics for a script author, not a channel a script may use to fill an operator’s disk.

pub const DEFAULT_MAX_BLOCKING_PER_EVALUATION: Duration

Default wall clock the host functions may block one evaluation for.

Name resolution blocks the worker thread, and the execution time limit cannot interrupt it, so the lookup count alone would still let one evaluation hold its worker for count times the dns timeout.

pub fn new() -> PacEnv

Create a PAC environment with the default configuration: the global dns resolver and the system clock.

pub fn maybe_with_resolver( self, resolver: Option<BoxDnsAddressResolver>, ) -> PacEnv

Resolve names through this resolver instead of the GlobalDnsResolver.

pub fn maybe_set_resolver( &mut self, resolver: Option<BoxDnsAddressResolver>, ) -> &mut PacEnv

Resolve names through this resolver instead of the GlobalDnsResolver.

pub fn with_resolver(self, resolver: BoxDnsAddressResolver) -> PacEnv

Resolve names through this resolver instead of the GlobalDnsResolver.

pub fn set_resolver(&mut self, resolver: BoxDnsAddressResolver) -> &mut PacEnv

Resolve names through this resolver instead of the GlobalDnsResolver.

pub fn without_resolver(self) -> PacEnv

Resolve names through this resolver instead of the GlobalDnsResolver.

pub fn unset_resolver(&mut self) -> &mut PacEnv

Resolve names through this resolver instead of the GlobalDnsResolver.

pub fn dns_timeout(&self) -> Duration

The timeout one dns lookup gets.

pub fn max_lookups_per_evaluation(&self) -> u32

How many dns lookups one evaluation may make.

pub fn max_glob_steps_per_evaluation(&self) -> u64

How many shExpMatch steps one evaluation may spend.

pub fn max_alerts_per_evaluation(&self) -> u32

How many alert calls one evaluation may log.

pub fn max_blocking_per_evaluation(&self) -> Duration

How long the host functions may block one evaluation.

pub fn ipv6_extensions(&self) -> bool

Whether the ipv6-aware extensions are defined.

pub fn with_dns_timeout(self, dns_timeout: Duration) -> PacEnv

Timeout for a single dns lookup made by a host function (defaults to Self::DEFAULT_DNS_TIMEOUT).

A lookup that exceeds it reports the host as unresolvable rather than failing the evaluation.

pub fn set_dns_timeout(&mut self, dns_timeout: Duration) -> &mut PacEnv

Timeout for a single dns lookup made by a host function (defaults to Self::DEFAULT_DNS_TIMEOUT).

A lookup that exceeds it reports the host as unresolvable rather than failing the evaluation.

pub fn with_max_lookups_per_evaluation(self, lookups: u32) -> PacEnv

How many distinct hosts one evaluation may resolve before further lookups fail it (defaults to Self::DEFAULT_MAX_LOOKUPS_PER_EVALUATION).

Repeats within an evaluation are served from its own cache and cost nothing. Exhausting the budget throws rather than reporting a host as unresolvable: a script must not be able to spend it and have the rule that follows quietly stop matching.

Only enforced for callers that arm the budget per evaluation, as PacResolver does.

pub fn set_max_lookups_per_evaluation(&mut self, lookups: u32) -> &mut PacEnv

How many distinct hosts one evaluation may resolve before further lookups fail it (defaults to Self::DEFAULT_MAX_LOOKUPS_PER_EVALUATION).

Repeats within an evaluation are served from its own cache and cost nothing. Exhausting the budget throws rather than reporting a host as unresolvable: a script must not be able to spend it and have the rule that follows quietly stop matching.

Only enforced for callers that arm the budget per evaluation, as PacResolver does.

pub fn with_sh_exp_match(self, sh_exp_match: PacShExpMatch) -> PacEnv

How shExpMatch reads its pattern (defaults to PacShExpMatch::Reference, what browsers do).

pub fn set_sh_exp_match(&mut self, sh_exp_match: PacShExpMatch) -> &mut PacEnv

How shExpMatch reads its pattern (defaults to PacShExpMatch::Reference, what browsers do).

pub fn with_ipv6_extensions(self, ipv6_extensions: bool) -> PacEnv

Define the ipv6-aware extensions — dnsResolveEx, isResolvableEx, isInNetEx, myIpAddressEx, sortIpAddressList and getClientVersion — and prefer a FindProxyForURLEx entry point (defaults to true).

Microsoft defines all six helpers and WinHTTP prefers the extended entry point; rama follows both behaviours. Chromium adopted five helpers but omits getClientVersion, while Firefox defines none of them. Turning the option off exposes only the classic surface.

pub fn set_ipv6_extensions(&mut self, ipv6_extensions: bool) -> &mut PacEnv

Define the ipv6-aware extensions — dnsResolveEx, isResolvableEx, isInNetEx, myIpAddressEx, sortIpAddressList and getClientVersion — and prefer a FindProxyForURLEx entry point (defaults to true).

Microsoft defines all six helpers and WinHTTP prefers the extended entry point; rama follows both behaviours. Chromium adopted five helpers but omits getClientVersion, while Firefox defines none of them. Turning the option off exposes only the classic surface.

pub fn with_max_blocking_per_evaluation(self, blocking: Duration) -> PacEnv

How long the host functions may block one evaluation before the rest fail it (defaults to Self::DEFAULT_MAX_BLOCKING_PER_EVALUATION).

pub fn set_max_blocking_per_evaluation( &mut self, blocking: Duration, ) -> &mut PacEnv

How long the host functions may block one evaluation before the rest fail it (defaults to Self::DEFAULT_MAX_BLOCKING_PER_EVALUATION).

pub fn with_max_alerts_per_evaluation(self, alerts: u32) -> PacEnv

How many alert calls one evaluation may write to the log before the rest are dropped (defaults to Self::DEFAULT_MAX_ALERTS_PER_EVALUATION).

pub fn set_max_alerts_per_evaluation(&mut self, alerts: u32) -> &mut PacEnv

How many alert calls one evaluation may write to the log before the rest are dropped (defaults to Self::DEFAULT_MAX_ALERTS_PER_EVALUATION).

pub fn with_max_glob_steps_per_evaluation(self, steps: u64) -> PacEnv

How many shExpMatch character comparisons one evaluation may spend before the evaluation fails (defaults to Self::DEFAULT_MAX_GLOB_STEPS_PER_EVALUATION).

pub fn set_max_glob_steps_per_evaluation(&mut self, steps: u64) -> &mut PacEnv

How many shExpMatch character comparisons one evaluation may spend before the evaluation fails (defaults to Self::DEFAULT_MAX_GLOB_STEPS_PER_EVALUATION).

pub fn with_local_addresses(self, local_addresses: PacLocalAddresses) -> PacEnv

Which local addresses myIpAddress() and myIpAddressEx() disclose to the script (defaults to browser behaviour, see PacLocalAddresses).

pub fn set_local_addresses( &mut self, local_addresses: PacLocalAddresses, ) -> &mut PacEnv

Which local addresses myIpAddress() and myIpAddressEx() disclose to the script (defaults to browser behaviour, see PacLocalAddresses).

pub fn with_promote_ipv4_in_net(self, promote_ipv4_in_net: bool) -> PacEnv

Compare an ipv4 address against an ipv6 isInNetEx prefix as its v4-mapped form, and vice versa (defaults to true, which is what browsers do).

Note this makes an ipv6 catch-all such as ::/0 match ipv4 addresses too; disable it to keep families strictly apart.

pub fn set_promote_ipv4_in_net( &mut self, promote_ipv4_in_net: bool, ) -> &mut PacEnv

Compare an ipv4 address against an ipv6 isInNetEx prefix as its v4-mapped form, and vice versa (defaults to true, which is what browsers do).

Note this makes an ipv6 catch-all such as ::/0 match ipv4 addresses too; disable it to keep families strictly apart.

pub fn maybe_with_clock( self, clock: Option<Arc<dyn Fn() -> Zoned + Sync + Send>>, ) -> PacEnv

Read the current time from this clock instead of the system one, so the time-based host functions can be pinned in tests.

pub fn maybe_set_clock( &mut self, clock: Option<Arc<dyn Fn() -> Zoned + Sync + Send>>, ) -> &mut PacEnv

Read the current time from this clock instead of the system one, so the time-based host functions can be pinned in tests.

pub fn with_clock(self, clock: Arc<dyn Fn() -> Zoned + Sync + Send>) -> PacEnv

Read the current time from this clock instead of the system one, so the time-based host functions can be pinned in tests.

pub fn set_clock( &mut self, clock: Arc<dyn Fn() -> Zoned + Sync + Send>, ) -> &mut PacEnv

Read the current time from this clock instead of the system one, so the time-based host functions can be pinned in tests.

pub fn without_clock(self) -> PacEnv

Read the current time from this clock instead of the system one, so the time-based host functions can be pinned in tests.

pub fn unset_clock(&mut self) -> &mut PacEnv

Read the current time from this clock instead of the system one, so the time-based host functions can be pinned in tests.

pub fn with_dns_resolver(self, resolver: impl DnsAddressResolver) -> PacEnv

Set the dns resolver, taking any DnsAddressResolver.

pub fn register( self, builder: JsRuntimeBuilder, ) -> Result<PacRuntimeBuilder, Box<dyn Error + Sync + Send>>

Register every PAC host function on the given runtime builder.

Requires an ambient tokio runtime: the dns host functions are synchronous and block the script’s worker thread on it.

Trait Implementations

impl Clone for PacEnv

fn clone(&self) -> PacEnv

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PacEnv

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

Formats the value using the given formatter.

impl Default for PacEnv

fn default() -> PacEnv

Returns the “default value” for a type.