Crate pac 

Available on crate features js and pac and std only.

Proxy Auto-Configuration (PAC) support for Rama.

A PAC script is a javascript configuration file exposing FindProxyForURL(url, host), which returns the proxies to use for a given request — the mechanism browsers and system proxy settings have used since Netscape. This crate parses what such a script returns (PacDirectives), evaluates scripts (PacResolver) and generates them (PacGenerator). SystemPacProxy adapts the evaluator to SystemProxyLayer when the operating system supplies the script URL.

Scripts are evaluated on a JsWorker: compiled once, called per request. Only run scripts you trust at least as much as your configuration files — see the [rama-js docs][rama_js#isolation-and-limits] on the reach of its limits.

PacProxyRoutesLayer fails closed by default when fetching or evaluating the script fails. Configuring PacFailurePolicy::Direct explicitly turns every such failure — including a timeout or exhausted host-function budget — into a direct connection; use that browser-like fail-open behavior only when proxy bypass is acceptable.

What one evaluation may spend

The guest execution deadline can interrupt JavaScript, not native work a host function does, so the host functions carry budgets of their own, reset per evaluation and configurable on PacEnv:

• distinct hosts resolved (PacEnv::DEFAULT_MAX_LOOKUPS_PER_EVALUATION) — without it, a script looping over dnsResolve turns one request into as many queries as its time limit allows. Repeats within an evaluation are served from its own cache and cost nothing, as they do in browsers;
• shExpMatch work (PacEnv::DEFAULT_MAX_GLOB_STEPS_PER_EVALUATION) — building and running a matcher is native work no deadline reaches;
• wall clock spent blocking (PacEnv::DEFAULT_MAX_BLOCKING_PER_EVALUATION) — a lookup blocks the worker where the execution time limit cannot reach;
• alert calls (PacEnv::DEFAULT_MAX_ALERTS_PER_EVALUATION) — a log is not a channel for a script to fill an operator’s disk through.

Microsoft’s ipv6-aware extensions — dnsResolveEx and friends — are defined by default. Chromium defines that set except for getClientVersion, while Firefox defines none of it; rama supports the full Microsoft surface and WinHTTP’s FindProxyForURLEx preference. The extensions can be left out with PacEnv::set_ipv6_extensions.

Exhausting any of the first three fails the evaluation rather than answering false: a client must not be able to spend a budget until a rule stops matching. Alerts past the cap are simply dropped, since losing a diagnostic line is not a routing decision. myIpAddress results are cached for the evaluation, and the addresses it may disclose are bounded by PacLocalAddresses.

Structs

FetchPacScript

Always fetches the script, through the given http client.

PacBudgetHandle

Arms the budgets of the runtime it came from.

PacDirectives

The ordered proxy list a PAC script returned: try each in turn, falling back to the next when one is unreachable.

PacEnv

Builds the PAC javascript environment.

PacGenerator

Builds a PAC script that routes matching hosts to given proxies.

PacProxyRoutesLayer

Inserts the ProxyRoutes a PAC script selects for each request, for a ProxyRoutesConnector further down the stack to connect through.

PacProxyRoutesService

See PacProxyRoutesLayer.

PacResolver

Evaluates a PAC script to decide how a request should be proxied.

PacResolverBuilder

Builds a PacResolver.

PacRuntimeBuilder

A PAC environment bound to exactly one javascript runtime.

PacScript

The source of a PAC script.

PacScriptCache

See PacScriptCacheLayer.

PacScriptCacheLayer

Keeps a fetched script for ttl, so an always-fetching provider does not hit the network per request.

StaticPacScript

Serves one script, ignoring the uri: for scripts that ship with the configuration rather than being fetched.

SystemPacProxy

Creates reusable PacResolver services for system-configured PAC URLs.

SystemPacResolver

Resolves routes for requests using one system-configured PAC script.

Enums

PacDirective

One proxy instruction returned by a PAC script.

PacFailurePolicy

What to route through when PAC resolution fails for any reason, including script fetch, parse, execution, timeout, or host-function budget failure.

PacLocalAddresses

Which local addresses myIpAddress() and myIpAddressEx() disclose.

PacShExpMatch

How shExpMatch(str, shexp) reads its pattern.

PacUrlSanitize

How much of the request uri a PAC script gets to see.

Constants

DEFAULT_LOCAL_IP_SCOPES

Scopes a PAC script is shown by default: every address a proxy decision can sensibly be based on. Loopback and link-local are excluded, as they route nowhere useful.

DEFAULT_PAC_MAX_ROUTES

Default maximum number of routes one script verdict may publish.

Type Aliases

PacClock

The clock a PAC environment reads the current time from.