PR#1411 Documentation

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?}

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
+The initial value of @racket[current-proxy-servers] is configured on demand from environment
-environment variables @indexed-envvar{plt_http_proxy} and @indexed-envvar{http_proxy},
+variables. Proxies for each URL scheme are configured from two variables each:
-where the former takes precedence over the latter.
+
+@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,
+@litchar{http://}@nonterm{hostname}@litchar{:}@nonterm{portno}.
-an error will be logged to a @racket[net/url] logger.
+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