FindProxyForURL() (Function/proxy.pac)

The main function in a proxy.pac file.

Availability:

JavaScript - 1.2
Netscape - 4.0
JavaScript syntax:NFindProxyForURL(aFullURL, aHostname)
Argument list:aFullURLThe complete URL to be checked for proxy access.
aHostnameThe hostname component of a URL for convenience

This function is called at request time for every URL. Therefore any lengthy and complex coding in here is going to be detrimental to the performance of your browser.

The String and Math object methods/functions are available in this context.

The return value from this function tells the browser how to reach the target URL.

For directly connected sites, the value "DIRECT" should be returned. This is usually appropriate for hosts within the same domain or on the same sub-net. The functions isPlainHostName() and isInNet() both return true for machines that should use DIRECT connection. However only one of them needs to return true for this to be the desired outcome. If both are false, then either a SOCKS gateway or PROXY server is needed.

For secure access using the HTTPS: protocol, the function might return "SOCKS" plus some details of the SOCKS host and port to use. You may choose to perform secure access by some other means.

For the remaining cases, your script should probably return "PROXY" with details of the proxy server (or servers) to use. If more than one proxy server is returned, they are consulted in the order they are listed. This gives you an opportunity to add some load balancing logic if you care to. That is quite important if you have more than one proxy server, since you might return the proxies in the same order every time. That would more-or-less guarantee that the first one was loaded until it simply couldn't respond any more and the second would only kick in as a last resort. Randomizing the order in which they are presented ensures the work is fairly divided between them.

This function must return a very specific result. The following values are examples:

"DIRECT"

"SOCKS sockshost:1081"

"PROXY proxy1:1080 ; proxy2:1080"

Here we provide an example based on the one provided in the Wrox Instant JavaScript book (by Nigel MacFarlane) that illustrates all of these capabilities. The logic is unraveled to illustrate the selection technique at the expense of a minor performance hit.

Example code:

   // Example proxy.pac file
   // Example proxy.pac file
   function FindProxyForURL(aFullURL, aHostname)
   {
      // Check for hosts in the same domain as the client
      if(isPlainHostName(aHostname))
      {
         return "DIRECT";
      }
      // Check for hosts in the same IP sub-net
      if(isInNet(aHostname, "192.168.1.0"))
      {
         return "DIRECT";
      }
      // Check for secure http: protocol
      if(aFullURL.substring(0, 6) == "https:")
      {
         return "SOCKS sockshost:1081";
      }
      // Check for secure news protocol
      if(aFullURL.substring(0, 6) == "snews:")
      {
         return "SOCKS sockshost:1081";
      }
      // Return a randomly selected proxy list
      if(Math.random() < 0.5)
      {
         return "PROXY proxy1:1080 ; proxy2:1080";
      }
      else
      {
         return "PROXY proxy2:1080 ; proxy1:1080";
      }
   }

See also:isInNet(), isPlainHostName(), Proxies, proxy.pac