PR#1411 Documentation
This commit is contained in:
Tim Brown
parent
321000b831
commit
a5583485b6
|
|
@ -32,7 +32,7 @@ Returns a fresh HTTP connection.
|
|||
}
|
||||
|
||||
@defproc[(http-conn-open! [hc http-conn?] [host (or/c bytes? string?)]
|
||||
[#:ssl? ssl? (or/c boolean? ssl-client-context? symbol?) #f]
|
||||
[#:ssl? ssl? base-ssl?-tnl/c #f]
|
||||
[#:port port (between/c 1 65535) (if ssl? 443 80)])
|
||||
void?]{
|
||||
|
||||
|
|
@ -46,7 +46,7 @@ If @racket[hc] is live, the connection is closed.
|
|||
}
|
||||
|
||||
@defproc[(http-conn-open [host (or/c bytes? string?)]
|
||||
[#:ssl? ssl? (or/c boolean? ssl-client-context? symbol?) #f]
|
||||
[#:ssl? ssl? base-ssl?-tnl/c #f]
|
||||
[#:port port (between/c 1 65535) (if ssl? 443 80)])
|
||||
http-conn?]{
|
||||
|
||||
|
|
@ -138,7 +138,7 @@ Calls @racket[http-conn-send!] and @racket[http-conn-recv!] in sequence.
|
|||
}
|
||||
|
||||
@defproc[(http-sendrecv [host (or/c bytes? string?)] [uri (or/c bytes? string?)]
|
||||
[#:ssl? ssl? (or/c boolean? ssl-client-context? symbol?) #f]
|
||||
[#:ssl? ssl? base-ssl?-tnl/c #f]
|
||||
[#:port port (between/c 1 65535) (if ssl? 443 80)]
|
||||
[#:version version (or/c bytes? string?) #"1.1"]
|
||||
[#:method method (or/c bytes? string? symbol?) #"GET"]
|
||||
|
|
@ -157,6 +157,36 @@ response, which is why there is no @racket[#:closed?] argument like
|
|||
|
||||
}
|
||||
|
||||
@defproc[(http-conn-CONNECT-tunnel [proxy-host (or/c bytes? string?)]
|
||||
[proxy-port (between/c 1 65535)]
|
||||
[target-host (or/c bytes? string?)]
|
||||
[target-port (between/c 1 65535)]
|
||||
[#:ssl? ssl? base-ssl?/c #f])
|
||||
(values base-ssl?/c input-port? output-port? (-> port? void?))]{
|
||||
Creates an HTTP connection to @racket[proxy-host] (on port @racket[proxy-port])
|
||||
and invokes the HTTP ``CONNECT'' method to provide a tunnel to
|
||||
@racket[target-host] (on port @racket[target-port]).
|
||||
|
||||
The SSL context or symbol, if any, provided in @racket[ssl?]
|
||||
is applied to the gateway ports using @racket[ports->ssl-ports] (or @racket[ports->win32-ssl-ports]).
|
||||
|
||||
The function returns four values:
|
||||
@itemize[
|
||||
@item{If @racket[ssl?] was not provided then @racket[#f].
|
||||
|
||||
If it was a protocol symbol, then a new @racket[ssl-client-context] is created, otherwise the
|
||||
current value of @racket[ssl?] is used as the @racket[ssl-client-context] to use. This client
|
||||
context is negotiated with the SSL server and returned as the first value}
|
||||
@item{An @racket[input-port?], which is connected to read from the tunnelled service}
|
||||
@item{An @racket[output-port?], which is connected to write to the tunnelled service}
|
||||
@item{An abandon function, which when applied either returned, port will abandon it, in a manner
|
||||
similar to @racket[tcp-abandon-port]}
|
||||
]
|
||||
The SSL context or symbol, if any, provided in @racket[ssl?]
|
||||
is applied to the gateway ports using @racket[ports->ssl-ports] (or @racket[ports->win32-ssl-ports])
|
||||
and the negotiated client context is returned
|
||||
}
|
||||
|
||||
@defthing[data-procedure/c chaperone-contract?]{
|
||||
|
||||
Contract for a procedure that accepts a procedure of one
|
||||
|
|
@ -165,6 +195,23 @@ argument, which is a string or byte string:
|
|||
|
||||
}
|
||||
|
||||
@defthing[base-ssl?/c contract?]{
|
||||
Base contract for the definition of the SSL context (passed in @racket[ssl?]) of an
|
||||
@racket[http-conn-CONNECT-tunnel]:
|
||||
@racket[(or/c boolean? ssl-client-context? symbol?)].
|
||||
|
||||
If @racket[ssl?] is not @racket[#f] then @racket[ssl?] is used as an argument to
|
||||
@racket[ssl-connect] to, for example, check certificates.
|
||||
}
|
||||
|
||||
@defthing[base-ssl?-tnl/c contract?]{
|
||||
Contract for a @racket[base-ssl?/c] that might have been applied to a tunnel.
|
||||
It is either a @racket[base-ssl?/c], or a @racket[base-ssl?/c] consed onto a list of an
|
||||
@racket[input-port?], @racket[output-port?], and an abandon function
|
||||
(e.g. @racket[tcp-abandon-port]):
|
||||
@racket[(or/c base-ssl?/c (list/c base-ssl?/c input-port? output-port? (-> port? void?)))]
|
||||
}
|
||||
|
||||
@section[#:tag "faq"]{Troubleshooting and Tips}
|
||||
|
||||
@subsection{How do I send properly formatted POST form requests?}
|
||||
|
|
|
|||
|
|
@ -478,12 +478,12 @@ When a @racket[header] argument is supplied, it is passed along to the
|
|||
The connection is made in such a way that the port is closed before
|
||||
@racket[call/input-url] returns, no matter how it returns. In
|
||||
particular, it is closed if @racket[handle] raises an exception, or if
|
||||
the connection process is interruped by an asynchronous break
|
||||
the connection process is interrupted by an asynchronous break
|
||||
exception.}
|
||||
|
||||
@deftogether[(
|
||||
@defparam[current-proxy-servers mapping (listof (list/c string? string? (integer-in 0 65535)))]
|
||||
@defthing[proxiable-url-schemes (listof string?) #:value '("http")]
|
||||
@defthing[proxiable-url-schemes (listof string?) #:value '("http" "https" "git")]
|
||||
)]{
|
||||
|
||||
The @racket[current-proxy-servers] parameter determines a mapping of proxy servers used for
|
||||
|
|
@ -492,7 +492,7 @@ connections. Each mapping is a list of three elements:
|
|||
@itemize[
|
||||
|
||||
@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"];}
|
||||
that can be proxied}
|
||||
|
||||
@item{the proxy server address; and}
|
||||
|
||||
|
|
@ -500,16 +500,28 @@ connections. Each mapping is a list of three elements:
|
|||
|
||||
]
|
||||
|
||||
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.
|
||||
The initial value of @racket[current-proxy-servers] is configured on demand from environment
|
||||
variables. Proxies for each URL scheme are configured from two variables each:
|
||||
|
||||
@itemize[
|
||||
@item{@indexed-envvar{plt_http_proxy} and @indexed-envvar{http_proxy}, configure the HTTP
|
||||
proxy, where the former takes precedence over the latter. HTTP requests will be proxied using an
|
||||
HTTP proxy server connection}
|
||||
@item{@indexed-envvar{plt_https_proxy} and @indexed-envvar{https_proxy}, configure the HTTPS
|
||||
proxy, where the former takes precedence over the latter. HTTPS connections are proxied using an
|
||||
HTTP ``CONNECT'' tunnel}
|
||||
@item{@indexed-envvar{plt_git_proxy} and @indexed-envvar{git_proxy}, configure the GIT
|
||||
proxy, where the former takes precedence over the latter. GIT connections are proxied using an
|
||||
HTTP ``CONNECT'' tunnel}
|
||||
]
|
||||
|
||||
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.
|
||||
@litchar{http://}@nonterm{hostname}@litchar{:}@nonterm{portno}.
|
||||
If any other components of the URL are provided, a warning will be logged to a @racket[net/url]
|
||||
logger.
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user