new entries for current-proxy-servers et al.

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
+Currently, the only proxiable scheme is @racket["http"].
-mapping is the empty list (i.e., no proxies).}
+
+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?]{