diff --git a/pkgs/net-doc/net/scribblings/http-client.scrbl b/pkgs/net-doc/net/scribblings/http-client.scrbl index 34d65d3ff5..6505dbf059 100644 --- a/pkgs/net-doc/net/scribblings/http-client.scrbl +++ b/pkgs/net-doc/net/scribblings/http-client.scrbl @@ -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?} diff --git a/pkgs/net-doc/net/scribblings/url.scrbl b/pkgs/net-doc/net/scribblings/url.scrbl index d6e402b455..9d18a1f64e 100644 --- a/pkgs/net-doc/net/scribblings/url.scrbl +++ b/pkgs/net-doc/net/scribblings/url.scrbl @@ -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