suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc refinments and corrections

Browse Source 
Adjust docs to match the final, less exposed mechanism for
initializing parameters from environment variables.
This commit is contained in:
Matthew Flatt 2015-11-19 16:10:01 -07:00
parent ef8f42f5b0
commit 57a156351d
1 changed files with 29 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
net-doc/net/scribblings/url.scrbl
View File

@ -479,8 +479,8 @@ connections. Each mapping is a list of three elements:
@itemize[
@item{the URL scheme, such as @racket["http"]; @racket[proxiable-url-schemes] lists the URL schemes
that can be proxied. Currently, the only proxiable scheme is @racket["http"].}
@item{the URL scheme, such as @racket["http"], where @racket[proxiable-url-schemes] lists the URL schemes
that can be proxied; currently, the only proxiable scheme is @racket["http"];}
@item{the proxy server address; and}
@ -488,28 +488,26 @@ connections. Each mapping is a list of three elements:
]
@racket[current-proxy-servers] can be configured from the environment. If
it has no entry for a particular URL scheme, then the environment
variables @litchar["plt_http_proxy"] and @litchar["http_proxy"] are used. This is done via a promise
that is forced by @racket[proxy-server-for].
The initial value of @racket[current-proxy-servers] is configured on demand from the
environment variables @indexed-envvar{plt_http_proxy} and @indexed-envvar{http_proxy},
where the former takes precedence over the latter.
Each environment variable contains a single URL of the form
@litchar{http://}@nonterm{hostname}@litchar{:}@nonterm{portno}. If any other components of the URL are provided,
an error will be logged to a @racket[net/url] logger.
The environment variables contain 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 is the empty list (i.e., no proxies).}
The default mapping 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:
i.e. without resort to @racket[current-proxy-servers]. It is a list of
@itemize[
@item{strings that match host names exactly}
@item{strings that match host names exactly; and}
@item{regexps that match host by pattern}
@item{regexps that match host by pattern.}
]
@ -518,49 +516,38 @@ host name is checked against @racket[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.
@racket[current-no-proxy-servers] can be configured from the environment.
The environment variables @litchar["plt_no_proxy"] and @litchar["no_proxy"]
are used. This is done via a promise that is forced by @racket[proxy-server-for].
These environment variables are comma-separated list of ``patterns''.
A pattern from an environment variable is one of:
The initial value of @racket[current-no-proxy-servers] is configured on demand from the
environment variables @indexed-envvar{plt_no_proxy} and @indexed-envvar{no_proxy},
where the former takes precedence over the latter.
Each environment variable's value is parsed as a comma-separated list of ``patterns,''
where a pattern is one of:
@margin-note{This parsing is consistent with the @litchar["no_proxy"] environment
variable used by other software, albeit not consistent with the regexps
stored in @racket[current-no-proxy-servers].}
@itemize[
@item{a string beginning with a @litchar{.} (period). 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
@item{a string beginning with a @litchar{.} (period): converted to a
regexp that performs a suffix match on a destination host name;
e.g. @litchar[".racket-lang.org"] matches 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 software, albeit not consistent with the regexps
stored in @racket[current-no-proxy-servers]}
@litchar["pkgs.racket-lang.org.uk"];
}
@item{any other string -- is converted to a regexp which matches the string exactly}
@item{any other string: converted to a regexp that matches the string 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))]{
(or/c (list/c string? string? (integer-in 0 65535)) #f)]{
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.
and @racket[host], or @racket[#f] if no proxy is to be used.}
The process that loads environment variables into @racket[current-proxy-servers]
and @racket[current-no-proxy-servers] is held on a promise that is forced by
@racket[proxy-server-for]. This means that:
@itemize[
@item{calling @racket[proxy-server-for] might change the list of
@racket[current-proxy-servers] and @racket[current-no-proxy-servers]}
@item{to resolve proxy/no-proxy values from the environment, call @racket[(proxy-server-for #f)]}
]}
@defproc[(url-exception? [x any/c])
boolean?]{