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).

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#limits-are-guardrails-not-a-sandbox] on the reach of its limits.

What one evaluation may spend

The execution time limit bounds bytecode, not the 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.

Enums

PacDirective

One proxy instruction returned by a PAC script.

PacFailurePolicy

What to route through when the script cannot be consulted.

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, which is what browsers report. 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.