diff --git a/net-doc/net/scribblings/url.scrbl b/net-doc/net/scribblings/url.scrbl index e604e9244f..8f150d3fae 100644 --- a/net-doc/net/scribblings/url.scrbl +++ b/net-doc/net/scribblings/url.scrbl @@ -469,7 +469,6 @@ particular, it is closed if @racket[handle] raises an exception, or if the connection process is interruped by an asynchronous break exception.} - @defparam[current-proxy-servers mapping (listof (list/c string? string? (integer-in 0 65535)))]{ A parameter that determines a mapping of proxy servers used for @@ -485,8 +484,60 @@ connections. Each mapping is a list of three elements: ] -Currently, the only proxiable scheme is @racket["http"]. The default -mapping is the empty list (i.e., no proxies).} +Currently, the only proxiable scheme is @racket["http"]. + +The environment variable @litchar["PLT_HTTP_PROXY"] can by used to set +an initial value for @racket[current-proxy-servers]. It contains a +single URL of the form: @litchar{http://hostname:portno}. If any other +components of the URL are provided, an error will be logged to the +@racket[net/url] logger. + +The default mapping (or the mapping if @litchar["PLT_HTTP_PROXY"] is +not a valid URL) is the empty list (i.e., no proxies).} + +@defparam[current-no-proxy-servers dest-hosts-list (listof (or/c string? regexp?))]{ + +A parameter that determines which servers will be accessed directly +i.e. without resort to @racket[current-proxy-servers]. It is a list of: + +@itemize[ + @item{strings that match host names exactly} + @item{regexps that match host by pattern} +] + +If a proxy server is defined for a URL scheme, then the destination +host name is checked against @[current-no-proxy-servers]. The proxy +is used if and only if the host name does not match (by the definition +above) any in the list. + +The environment variable @litchar["PLT_NO_PROXY"] can by used to set +an initial value for @racket[current-no-proxy-servers]. It is a +comma-separated list of ``patterns''. A pattern from the environment +variable is one of: + +@itemize[ + @item{a string beginning with a @litchar{.} . This is converted to a + regexp which performs a suffix match on a destination host name, + e.g. @litchar[.racket-lang.org] will match destinations of + @litchar[doc.racket-lang.org], @litchar[pkgs.racket-lang.org], but + neither @litchar[doc.bracket-lang.org] nor + @litchar[pkgs.racket-lang.org.uk]. + @margin-note{This is consistent with the @litchar["NO_PROXY"] environment + variable used by other programs, albeit not consistent with the regexps + stored in @racket[current-no-proxy-servers]} + } + @item{any other string -- is kept as a string to be matched exactly} +] + +} + +@defproc[(proxy-server-for + [url-schm string?] + [dest-host-name (or/c false/c string?) #f]) + (list/c string? string? (integer-in 0 65535))]{ +Returns the proxy server entry for the combination of @racket[url-schm] and @racket[host], or + @racket[#f] if no proxy is to be used. +} @defproc[(url-exception? [x any/c]) boolean?]{