JavaScript Functions and Environment

The JavaScript language has several predefined functions and environmental conditions that are useful with proxying. Each of these functions checks whether a certain condition is met and then returns a value of true or false. The related utility functions are an exception because they return a DNS host name or IP address. You can use these functions in the main FindProxyForURL() function to determine what return value to send to the browser. The examples later in this chapter provide ideas on using these functions.

Each of the functions or environmental conditions is described in this section. The functions and environmental conditions that apply to the browser integration with the proxy are:

• The host name functions are:

  • dnsDomainIs()()

  • isInNet()()

  • isPlainhost name()()

  • isResolvable()()

  • localHostOrDomainIs()()

• Utility functions:

  • dnsDomainLevels()

  • dnsResolve()

  • myIpAddress()

• URL/host name-based condition:

  • shExpMatch()

• Time-based conditions:

  • dateRange()

  • timeRange()

  • weekdayRange()

Hostname-Based Functions

The hostname-based functions let you use the host name or IP address to determine which proxy, if any, to use.

dnsDomainIs()(host, domain)

The dnsDomainIs()() function detects whether the URL host name belongs to a given DNS domain. This function is useful when you are configuring the browser not to use proxies for the local domain, as illustrated in Example 1: Proxy All Servers Except Local Hosts and Example 2: Proxy Local Servers Outside the Firewall.

This function is also useful when you are using multiple proxies for load balancing in situations where the proxy that receives the request is selected from a group of proxies based on which DNS domain the URL belongs to. For example, if you are load balancing by directing URLs containing .edu to one proxy and those containing .com to another proxy, you can check the URL host name using dnsDomainIs()().

Parameters

host is the host name from the URL.

domain is the domain name to test the host name against.

Return Values

true or false

Examples

The following statement would be true:

dnsDomainIs("www.example.com", ".example.com")

The following statements would be false:

dnsDomainIs("www", ".example.com") dnsDomainIs("www.mcom.com", 
	".example.com")

isInNet()(host, pattern, mask)

The isInNet()() function enables you to resolve a URL host name to an IP address and test whether it belongs to the subnet specified by the mask. This is the same type of IP address pattern matching that SOCKS uses. See Example 4: Connect Directly to a Subnet.

Parameters:

host is a DNS host name or IP address. If a host name is passed, this function will resolve it into an IP address.

pattern is an IP address pattern in the dot-separated format

mask is the IP address pattern mask that determines which parts of the IP address should be matched against. A value of 0 means ignore; 255 means match. This function is true if the IP address of the host matches the specified IP address pattern.

Return Values

true or false

Examples

This statement is true only if the IP address of the host matches exactly 198.95.249.79 exactly:

isInNet(host, "198.95.249.79", "255.255.255.255")

This statement is true only if the IP address of the host matches 198.95.*.*: isInNet(host, "198.95.0.0", "255.255.0.0")

isPlainhost name()(host)

The isPlainhost name()() function detects whether the host name in the requested URL is a plain host name or a fully qualified domain name. This function is useful if you want the browser to connect directly to local servers, as illustrated in Example 1: Proxy All Servers Except Local Hosts and Example 2: Proxy Local Servers Outside the Firewall.

Parameters

host is the host name from the URL, excluding the port number only if the host name has no domain name (no dotted segments).

Return Values

true if host is local; false if host is remote

Example

isPlainhost name("host")

If host is a string like www, then the function returns true. If host is a string like www.example.com, the function returns false.

isResolvable()(host)

If the DNS inside the firewall recognizes only internal hosts, you can use the isResolvable()() function to test whether a host name is internal or external to the network. Using this function, you can configure the browser to use direct connections to internal servers and to use the proxy only for external servers. This function is useful at sites where the internal hosts inside the firewall are able to resolve the DNS domain name of other internal hosts, but all external hosts are unresolvable. The isResolvable()() function consults DNS, attempting to resolve the host name into an IP address. See Example 3: Proxy Only Unresolved Hosts

Parameters

host() is the host name from the URL.

Return Values

true if the function can resolve the host name, false if it cannot

Example

isResolvable("host")

If host() is a string like www and can be resolved through DNS, then this function returns true.

localHostOrDomainIs()(host, hostdom)

ThelocalHostOrDomainIs()() function specifies local hosts that might be accessed by either the fully qualified domain name or the plain host name. See Example 2: Proxy Local Servers Outside the Firewall.

The localHostOrDomainIs()() function returns true if the host name matches the specified host name exactly or if there is no domain name part in the host name that the unqualified host name matches.

Parameters

host is the host name from the URL.

hostdom is the fully qualified host name to match.

Return Values

true or false

Examples

The following statement is true (exact match):

localHostOrDomainIs("www.example.com", "www.example.com")

The following statement is true (host name match, domain name not specified):

localHostOrDomainIs("www", "www.example.com")

The following statement is false (domain name mismatch):

localHostOrDomainIs("www.mcom.com", "www.example.com")

The following statement is false (host name mismatch):

localHostOrDomainIs("home.example.com", "www.example.com")

Utility Functions

The utility functions enable you to find out domain levels, the host on which the browser is running, or the IP address of a host.

dnsDomainLevels()(host)

The dnsDomainLevels()() function finds the number of DNS levels (number of dots) in the URL host name.

Parameters

host is the host name from the URL.

Return Value

number (integer) of DNS domain levels.

Examples

dnsDomainLevels("www") returns 0.

dnsDomainLevels("www.example.com") returns 2.

dnsResolve()(host)

The dnsResolve()() function resolves the IP address of the given host, typically from the URL. This function is useful if the JavaScript function has to do more advanced pattern matching than can be done with the existing functions.

Parameters

host is the host name to resolve. Resolves the given DNS host name into an IP address, and returns it in the dot-separated format as a string.

Return Value

dotted quad IP address as a string value

Example

The following example would return the string 198.95.249.79.

dnsResolve("home.example.com")

myIpAddress()()

The myIpAddress()() function is useful when the JavaScript function has to behave differently depending on the host on which the browser is running. This function returns the IP address of the computer that is running the browser.

Return Value

dotted quad IP address as a string value

Example:

The following example returns the string 198.95.249.79 if you are running Navigator on the computer home.example.com.

myIpAddress()

URL/Host-Name-Based Condition

You can match host names or URLs for load balancing and routing.

shExpMatch()(str, shexp)

The shExpMatch()() function matches either URL host names or URLs themselves. The main use of this function is for load balancing and intelligent routing of URLs to different proxy servers.

Parameters

str is any string to compare (for example, the URL or the host name).

shexp is a shell expression against which to compare.

This expression is true if the string matches the specified shell expression. See Example 6: Balance Proxy Load With shExpMatch()().

Returns Values

true or false

Examples

The first example returns true. The second example returns false.

shExpMatch("http://home.example.com/people/index.html",
            ".*/people/.*")
shExpMatch("http://home.example.com/people/yourpage/index.html",
            ".*/mypage/.*")

Time-Based Conditions

You can make the FindProxyForURL function behave differently depending on the date, time, or day of the week.

dateRange() (day, month, year...)

The dateRange()() function detects a particular date or a range of dates, such as April 19th, 1996 through May 3rd, 1996. This function is useful if you want the FindProxyForURL() function to act differently depending on the day week, for example, if maintenance down time is regularly scheduled for one of the proxies.

The date range can be specified several ways:

dateRange(day)dateRange(day1, day2)dateRange(mon)dateRange(month1, month2)dateRange(year)dateRange(year1, year2)dateRange(day1, month1, day2, month2)dateRange(month1, year1, month2, year2)dateRange(day1, month1, year1, day2, month2, year2)dateRange(day1, month1, year1, day2, month2, year2, gmt)

Parameters

day is an integer between 1 and 31 for the day of month.

month is one of the month strings: JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC

year is a four-digit integer for the year number (for example, 1996).

gmt is either the string “GMT”, which indicates that time comparisons should occur in Greenwich Mean Time, or is left blank so that times are assumed to be in the local time zone. The GMT parameter can be specified in any of the call profiles, always as the last parameter. If only a single value is specified from each category (day, month, year), the function returns a true value only on days that match that specification. If two values are specified, the result is true from the first time specified through the second time specified.

Examples

This statement is true on the first day of each month, local time zone: dateRange(1)

This statement is true on the first day of each month, Greenwich Mean Time: dateRange(1, "GMT")

This statement is true for the first half of each month: dateRange(1, 15)

This statement is true on the 24th of December each year: dateRange(24, "DEC")

This statement is true on the 24th of December, 1995: dateRange(24, "DEC", 1995)

This statement is true during the first quarter of the year: dateRange("JAN", "MAR")

This statement is true from June 1st through August 15th, each year: dateRange(1, "JUN", 15, "AUG")

This statement is true from June 1st, 1995, until August 15th, 1995: dateRange(1, "JUN", 15, 1995, "AUG", 1995)

This statement is true from October 1995 through March 1996: dateRange("OCT", 1995, "MAR", 1996)

This statement is true during the entire year of 1995: dateRange(1995)

This statement is true from the beginning of 1995 until the end of 1997: dateRange(1995, 1997)

timeRange (hour, minute, second...)

The timeRange() function detects a particular time of day or a range of time, such as 9 p.m. through 12 a.m. This function is useful if you want the FindProxyForURL() function to act differently depending on what time it is.

timeRange(hour)timeRange(hour1, hour2)timeRange(hour1, min1, hour2, min2)timeRange(hour1, min1, sec1, hour2, min2, sec2)

Parameters:

hour is the hour from 0 to 23. 0 is midnight, 23 is 11:00 p.m.

min is the number of minutes from 0 to 59.

sec is the number of seconds from 0 to 59.

gmt is either the string GMT for GMT time zone, or not specified for the local time zone. This parameter can be used with each of the parameter profiles and is always the last parameter.

Returns Values

true or false

Examples:

This statement is true from noon to 1:00 p.m: timerange(12, 13)

This statement is true noon to 12:59 p.m. GMT: timerange(12, "GMT")

This statement is true from 9:00 a.m. to 5:00 p.m: timerange(9, 17)

This statement is true between midnight and 30 seconds past midnight: timerange(0, 0, 0, 0, 0, 30)

weekdayRange()(wd1, wd2, gmt)

The weekdayRange() function detects a particular weekday or a range of weekdays, such as Monday through Friday. This is useful if you want the FindProxyForURL function to act differently depending on the day of the week.

Parameters

wd1and wd2are any one of these weekday strings: SUN MON TUE WED THU FRI SAT

gmt is either GMT for Greenwich Mean Time, or is left out for local time.

Only the first parameter, wd1, is mandatory. Either wd2, gmt, or both can be left out.

If only one parameter is present, the function returns a true value on the weekday that the parameter represents. If the string GMT is specified as a second parameter, times are given in GMT. Otherwise, the times are given in your local time zone.

If both wd1 and wd2 are defined, the condition is true if the current weekday is between those two weekdays. Bounds are inclusive. The order of parameters is important; “MON,” “WED” is Monday through Wednesday, but “WED,” “MON” is from Wednesday to the Monday of the next week.

Examples

This statement is true Monday through Friday (local time zone). weekdayRange("MON", "FRI")

This statement is true Monday through Friday, in Greenwich Mean Time. weekdayRange("MON", "FRI", "GMT")

This statement is true on Saturdays, local time.weekdayRange("SAT")

This statement is true on Saturdays, in Greenwich Mean Time.weekdayRange("SAT", "GMT")

This statement is true Friday through Monday (the order is important)weekdayRange("FRI", "MON")

Function Examples

This section provides detailed examples of the JavaScript functions.

Example 1: Proxy All Servers Except Local Hosts

In this example, the browser connects directly to all hosts that are not fully qualified and the ones that are in the local domain. All other hosts go through the proxy called w3proxy.example.com:8080.

---

Note –

If the proxy goes down, connections become direct automatically.

---

    function FindProxyForURL(url, host)
    {
        if (isPlainhost name(host) ||
            dnsDomainIs(host, ".example.com") ||
            dnsDomainIs(host, ".mcom.com"))
            return "DIRECT";
        else
            return "PROXY w3proxy.example.com:8080; DIRECT";
    }

Example 2: Proxy Local Servers Outside the Firewall

This example resembles Example 1: Proxy All Servers Except Local Hosts, but it uses the proxy for local servers that are outside the firewall. If hosts such as the main web server belong to the local domain but are outside the firewall and are only reachable through the proxy server, those exceptions are handled using the localHostOrDomainIs()() function:

    function FindProxyForURL(url, host)
    {
        if ((isPlainhost name(host) ||
        dnsDomainIs(host, ".example.com")) &&
        !localHostOrDomainIs(host, "www.example.com") &&
        !localHostOrDoaminIs(host, "merchant.example.com"))
            return "DIRECT";
        else
            return "PROXY w3proxy.example.com:8080; DIRECT";
    }

This example uses the proxy for all hosts except local hosts in the example.com domain. The hosts www.example.com and merchant.example.com also go through the proxy.

The order of the exceptions increases efficiency: localHostOrDomainIs()() functions get executed only for URLs that are in the local domain, not for every URL. In particular, notice the parentheses around the or expression before the and expression.

Example 3: Proxy Only Unresolved Hosts

This example works in an environment where internal DNS resolves only internal host names. The goal is to use a proxy only for hosts that aren’t resolvable.

    function FindProxyForURL(url, host)
    {
        if (isResolvable(host))
                return "DIRECT";
            else
                return "PROXY proxy.mydomain.com:8080";
    }

This example requires consulting the DNS every time. Therefore, you would group this example with other rules so that DNS is consulted only if other rules do not yield a result.

    function FindProxyForURL(url, host)
    {
        if (isPlainhost name(host) ||
            dnsDomainIs(host, ".mydomain.com") ||
            isResolvable(host))
            return "DIRECT";
        else
            return "PROXY proxy.mydomain.com:8080";
    }

Example 4: Connect Directly to a Subnet

In this example, all the hosts in a given subnet are connected to directly. Other hosts go through the proxy.

    function FindProxyForURL(url, host)
    {
        if (isInNet(host, "198.95.0.0", "255.255.0.0"))
            return "DIRECT";
        else
            return "PROXY proxy.mydomain.com:8080";
    }

You can minimize the use of DNS in this example by adding redundant rules in the beginning:

    function FindProxyForURL(url, host)
    {
        if (isPlainhost name(host) ||
            dnsDomainIs(host, ".mydomain.com") ||
            isInNet(host, "198.95.0.0", "255.255.0.0"))
            return "DIRECT";
        else
            return "PROXY proxy.mydomain.com:8080";
    }

Example 5: Balance Proxy Load With dnsDomainIs()()

This example is more sophisticated. The example uses four proxy servers, with one of them acting as a hot standby for the others. If any of the remaining three proxy servers goes down, the fourth one takes over. The three remaining proxy servers share the load based on URL patterns, which makes their caching more effective. Only one copy of any document exists on the three servers, as opposed to one copy on each of them. The load is distributed as shown in the following table.

Table 17–3 Balance Proxy Load

Proxy	Purpose
#1	.com domain
#2	.edu domain
#3	all other domains
#4	hot standby

All local accesses should be direct. All proxy servers run on port 8080. You can concatenate strings by using the + operator.

function FindProxyForURL(url, host)
{
    if (isPlainhost name(host) || dnsDomainIs(host, ".mydomain.com"))
        return "DIRECT";

    else if (dnsDomainIs(host, ".com"))
        return "PROXY proxy1.mydomain.com:8080; " +
              "PROXY proxy4.mydomain.com:8080";

    else if (dnsDomainIs(host, ".edu"))
        return "PROXY proxy2.mydomain.com:8080; " +
              "PROXY proxy4.mydomain.com:8080";

    else
        return "PROXY proxy3.mydomain.com:8080; " +
              "PROXY proxy4.mydomain.com:8080";
}

Example 6: Balance Proxy Load With shExpMatch()()

This example is essentially the same as Example 5: Balance Proxy Load With dnsDomainIs()(), but instead of using dnsDomainIs()(), this example uses shExpMatch()().

    function FindProxyForURL(url, host)
    {
    if (isPlainhost name(host) || dnsDomainIs(host, ".mydomain.com"))
        return "DIRECT";
    else if (shExpMatch(host, "*.com"))
        return "PROXY proxy1.mydomain.com:8080; " +
              "PROXY proxy4.mydomain.com:8080";
    else if (shExpMatch(host, "*.edu"))
        return "PROXY proxy2.mydomain.com:8080; " +
              "PROXY proxy4.mydomain.com:8080";
    else
        return "PROXY proxy3.mydomain.com:8080; " +
              "PROXY proxy4.mydomain.com:8080";
    }

Example 7: Proxying a Specific Protocol

You can set a proxy for a specific protocol. Most of the standard JavaScript functionality is available for use in the FindProxyForURL()() function. For example, to set different proxies based on the protocol, you can use the substring()() function.

    function FindProxyForURL(url, host)
    {
        if (url.substring(0, 5) == "http:") {
            return "PROXY http-proxy.mydomain.com:8080";
        }
        else if (url.substring(0, 4) == "ftp:") {
            return "PROXY ftp-proxy.mydomain.com:8080";
        }
        else if (url.substring(0, 7) == "gopher:") {
            return "PROXY gopher-proxy.mydomain.com:8080";
        }
        else if         (url.substring(0, 6) == "https:" ||
                url.substring(0, 6) == "snews:") {
            return "PROXY security-proxy.mydomain.com:8080";
        }
        else {
            return "DIRECT";
        }
    }

You can also accomplish this configuration by using the shExpMatch()() function; for example:

    ...
    if (shExpMatch(url, "http:*")) {
        return "PROXY http-proxy.mydomain.com:8080;
    }
    ...