Fix the bug. Standardise and document protocol upgrades.

5 files changed, 93 insertions, 8 deletions

diff --git a/doc/http.n b/doc/http.n
index 181b48b..a451f80 100644
--- a/doc/http.n
+++ b/doc/http.n
@@ -786,6 +786,40 @@ Subsequent GET and HEAD requests in a failed pipeline will also be retried.
 that the retry is appropriate\fR - specifically, the application must know
 that if the failed POST successfully modified the state of the server, a repeat POST
 would have no adverse effect.
+.SH "PROTOCOL UPGRADES"
+.PP
+The HTTP/1.1 \fBConnection\fR and \fBUpgrade\fR client headers inform the server
+that the client wishes to change the protocol used over the existing connection
+(RFC 7230).  This mechanism can be used to request a WebSocket (RFC 6455), a
+higher version of the HTTP protocol (HTTP 2 or 3), or TLS encryption.  If the
+server accepts the upgrade request, its response code will be 101.
+.PP
+To request a protocol upgrade when calling \fBhttp::geturl\fR, the \fB-headers\fR
+option must supply appropriate values for \fBConnection\fR and \fBUpgrade\fR, and
+the \fB-command\fR option must supply a command that implements the requested
+protocol and can also handle the server response if the server refuses the
+protocol upgrade.  For upgrade requests \fBhttp::geturl\fR ignores the value of
+option \fB-keepalive\fR, and always uses the value \fB0\fR so that the upgrade
+request is not made over a connection that is intended for multiple HTTP requests.
+.PP
+The Tcllib library \fBwebsocket\fR implements WebSockets, and makes the necessary
+calls to commands in the \fBhttp\fR package.
+.PP
+There is currently no native Tcl client library for HTTP/2 or HTTP/3.
+.PP
+The \fBUpgrade\fR mechanism is not used to request TLS in web browsers, because
+\fBhttp\fR and \fBhttps\fR are served over different ports.  It is used by
+protocols such as Internet Printing Protocol (IPP) that are built on top of
+\fBhttp(s)\fR and use the same TCP port number for both secure and insecure
+traffic.
+.PP
+In browsers, opportunistic encryption is instead implemented by the
+\fBUpgrade-Insecure-Requests\fR client header.  If a secure service is available,
+the server response code is a 307 redirect, and the response header
+\fBLocation\fR specifies the target URL.  The browser must call \fBhttp::geturl\fR
+again in order to fetch this URL.
+See https://w3c.github.io/webappsec-upgrade-insecure-requests/
+.PP
 .SH EXAMPLE
 .PP
 This example creates a procedure to copy a URL to a file while printing a
diff --git a/library/http/http.tcl b/library/http/http.tcl
index 326d9d8..92d3a5a 100644
--- a/library/http/http.tcl
+++ b/library/http/http.tcl
@@ -11,7 +11,7 @@
 package require Tcl 8.6-
 # Keep this in sync with pkgIndex.tcl and with the install directories in
 # Makefiles
-package provide http 2.9.6
+package provide http 2.9.7
 
 namespace eval http {
     # Allow resourcing to not clobber existing data
@@ -255,10 +255,49 @@ proc http::Finish {token {errormsg ""} {skipCB 0}} {
     if {[info commands ${token}EventCoroutine] ne {}} {
 	rename ${token}EventCoroutine {}
     }
+
+    # Is this an upgrade request/response?
+    set upgradeResponse 0
+    if {    [info exists state(upgradeRequest)]
+         && [info exists state(http)]
+         && $state(upgradeRequest)
+         && ([ncode $token] eq {101})
+    } {
+        # An upgrade must be requested by the client.
+        # If 101 response, test server response headers for an upgrade.
+        set connectionHd {}
+        set upgradeHd {}
+        if {[dict exists $state(meta) connection]} {
+            set connectionHd [string tolower [dict get $state(meta) connection]]
+        }
+        if {[dict exists $state(meta) upgrade]} {
+            set upgradeHd [string tolower [dict get $state(meta) upgrade]]
+        }
+        if {($connectionHd eq {upgrade}) && ($upgradeHd ne {})} {
+            set upgradeResponse 1
+        }
+    }
+
     if {  ($state(status) eq "timeout")
        || ($state(status) eq "error")
        || ($state(status) eq "eof")
-       || ([info exists state(-keepalive)] && !$state(-keepalive))
+    } {
+	set closeQueue 1
+	set connId $state(socketinfo)
+	set sock $state(sock)
+	CloseSocket $state(sock) $token
+    } elseif {$upgradeResponse} {
+	# Special handling for an upgrade request/response.
+	# - geturl ensures that this is not a "persistent" socket used for
+	#   multiple HTTP requests, so a call to KeepSocket is not needed.
+	# - Leave socket open, so a call to CloseSocket is not needed either.
+	# - Remove fileevent bindings.  The caller will set its own bindings.
+	# - THE CALLER MUST PROCESS THE UPGRADED SOCKET IN THE CALLBACK COMMAND
+	#   PASSED TO http::geturl AS -command callback.
+	catch {fileevent $state(sock) readable {}}
+	catch {fileevent $state(sock) writable {}}
+    } elseif {
+          ([info exists state(-keepalive)] && !$state(-keepalive))
        || ([info exists state(connection)] && ($state(connection) eq "close"))
     } {
 	set closeQueue 1
@@ -946,6 +985,13 @@ proc http::geturl {url args} {
     # c11a51c482]
     set state(accept-types) $http(-accept)
 
+    set state(upgradeRequest) [expr {
+           [dict exists $state(-headers) Upgrade]
+        && [dict exists $state(-headers) Connection]
+        && ([dict get $state(-headers) Connection] eq {Upgrade})
+        && ([dict get $state(-headers) Upgrade] ne {})
+    }]
+
     if {$isQuery || $isQueryChannel} {
 	# It's a POST.
 	# A client wishing to send a non-idempotent request SHOULD wait to send
@@ -961,8 +1007,13 @@ proc http::geturl {url args} {
 	    # There is a small risk of a race against server timeout.
 	    set state(-pipeline) 0
 	}
+    } elseif {$state(upgradeRequest)} {
+	# It's an upgrade request.  Method must be GET (untested).
+	# Force -keepalive to 0 so the connection is not made over a persistent
+	# socket, i.e. one used for multiple HTTP requests.
+	set state(-keepalive) 0
     } else {
-	# It's a GET or HEAD.
+	# It's a non-upgrade GET or HEAD.
 	set state(-pipeline) $http(-pipeline)
     }
 
diff --git a/library/http/pkgIndex.tcl b/library/http/pkgIndex.tcl
index 7249547..e12cf84 100644
--- a/library/http/pkgIndex.tcl
+++ b/library/http/pkgIndex.tcl
@@ -1,2 +1,2 @@
 if {![package vsatisfies [package provide Tcl] 8.6-]} {return}
-package ifneeded http 2.9.6 [list tclPkgSetup $dir http 2.9.6 {{http.tcl source {::http::config ::http::formatQuery ::http::geturl ::http::reset ::http::wait ::http::register ::http::unregister ::http::mapReply}}}]
+package ifneeded http 2.9.7 [list tclPkgSetup $dir http 2.9.7 {{http.tcl source {::http::config ::http::formatQuery ::http::geturl ::http::reset ::http::wait ::http::register ::http::unregister ::http::mapReply}}}]
diff --git a/unix/Makefile.in b/unix/Makefile.in
index 2acaf8a..de7f25b 100644
--- a/unix/Makefile.in
+++ b/unix/Makefile.in
@@ -950,9 +950,9 @@ install-libraries: libraries
 	    do \
 	    $(INSTALL_DATA) $$i "$(SCRIPT_INSTALL_DIR)/http1.0"; \
 	    done
-	@echo "Installing package http 2.9.6 as a Tcl Module";
+	@echo "Installing package http 2.9.7 as a Tcl Module";
 	@$(INSTALL_DATA) $(TOP_DIR)/library/http/http.tcl \
-		"$(MODULE_INSTALL_DIR)/8.6/http-2.9.6.tm"
+		"$(MODULE_INSTALL_DIR)/8.6/http-2.9.7.tm"
 	@echo "Installing package opt0.4 files to $(SCRIPT_INSTALL_DIR)/opt0.4/"
 	@for i in $(TOP_DIR)/library/opt/*.tcl; do \
 	    $(INSTALL_DATA) $$i "$(SCRIPT_INSTALL_DIR)/opt0.4"; \
diff --git a/win/Makefile.in b/win/Makefile.in
index 99f04c8..37d579b 100644
--- a/win/Makefile.in
+++ b/win/Makefile.in
@@ -735,8 +735,8 @@ install-libraries: libraries install-tzdata install-msgs
 	    do \
 	    $(COPY) "$$j" "$(SCRIPT_INSTALL_DIR)/http1.0"; \
 	    done;
-	@echo "Installing package http 2.9.6 as a Tcl Module";
-	@$(COPY) $(ROOT_DIR)/library/http/http.tcl "$(MODULE_INSTALL_DIR)/8.6/http-2.9.6.tm";
+	@echo "Installing package http 2.9.7 as a Tcl Module";
+	@$(COPY) $(ROOT_DIR)/library/http/http.tcl "$(MODULE_INSTALL_DIR)/8.6/http-2.9.7.tm";
 	@echo "Installing library opt0.4 directory";
 	@for j in $(ROOT_DIR)/library/opt/*.tcl; \
 	    do \