Note: only available since v0.13.0
:upgrade plugin is a “meta-plugin”, on top of which one can leverage the HTTP/1.1-only
Upgrade header to renegotiate an HTTP connection into some other protocol (it’s widely used by browser to establish
websocket connections, for example).
TODO: show example on how to build a tcp upgrade plugin.
TODO: link to websocket test.
Other plugins are built on top of it:
:h2c plugin leverages the
upgrade plugin to negotiate an “upgrade” of an unencrypted HTTP/1.1 connection into an HTTP/2 connection.
require "httpx" http = HTTPX.plugin(:h2c) http.get("http://nghttp2.org/blog/archives/", "http://nghttp2.org/") # Connected to nghttp2.org (18.104.22.168) port 80 (#6) # <- HEADLINE: "GET /blog/archives/ HTTP/1.1" # <- HEADER: User-Agent: httpx.rb/0.12.0 # <- HEADER: Accept: */* # <- HEADER: Connection: upgrade, http2-settings # <- HEADER: Upgrade: h2c # <- HEADER: HTTP2-Settings: AAIAAAAA # <- HEADER: Host: nghttp2.org # <- # WRITE: 170 bytes... # READ: 1552 bytes... # -> HEADLINE: 101 HTTP/1.1 # -> HEADER: connection: Upgrade # -> HEADER: upgrade: h2c # upgrading to h2c... # 1: <- HEADER: :status: 200 # 1: <- HEADER: content-type: text/html # 1: <- HEADER: ... # .... # 3: <- HEADER: :status: 200 # ...
Although it’s not recommend to use cleartext in the open internet nowadays, there are a few use cases where this scheme is useful, such as backennd-to-backend connection establishment in closed intranets, and GRPC, which uses
h2c to negotiate non-encrypted connections.
:upgrade/h2 plugin (which is actually automatically loaded with the
:upgrade plugin) takes advantage of an
Upgrade header that certain servers (such as apache) send with a response, advertising alternative protocols one can connect with (such as
h2). This is useful if the client or server do not support ALPN negotiation (like old TLS versions) and requires prior knowledge to connect.
After the first request, a new connection is established using HTTP/2, through which subsequent requests will be directed.
Next: Multipart uploads