use custom exception for failure to upgrade protocols

This allows Mint.WebSocket to return some details that may be
of interest when debugging or testing a failed WebSocket upgrade:
the response HTTP status code and response headers.

Author: the-mikedavis

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a
 Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.3.0 - 2022-02-27
+
+### Changed
+
+- Failure to upgrade now gives a `Mint.WebSocket.UpgradeFailureError`
+  as the error when a server returns a status code other than 101 for
+  HTTP/1 or a status code in the range 200..299 range for HTTP/2.
+
 ## 0.2.0 - 2022-02-17
 
 This release is a breaking change from the 0.1.0 series. This update removes

lib/mint/web_socket.ex

@@ -111,7 +111,7 @@ defmodule Mint.WebSocket do
   """
 
   alias __MODULE__.{Utils, Extension, Frame}
-  alias Mint.WebSocketError
+  alias Mint.{WebSocketError, WebSocket.UpgradeFailureError}
   alias Mint.{HTTP1, HTTP2}
   import Mint.HTTP, only: [get_private: 2, put_private: 3, protocol: 1]
 
@@ -129,7 +129,7 @@ defmodule Mint.WebSocket do
             private: %{},
             buffer: <<>>
 
-  @type error :: Mint.Types.error() | WebSocketError.t()
+  @type error :: Mint.Types.error() | WebSocketError.t() | UpgradeFailureError.t()
 
   @typedoc """
   Shorthand notations for control frames
@@ -330,8 +330,9 @@ defmodule Mint.WebSocket do
     do_new(protocol(conn), conn, status, response_headers)
   end
 
-  defp do_new(:http1, conn, status, _response_headers) when status != 101 do
-    {:error, conn, %WebSocketError{reason: :connection_not_upgraded}}
+  defp do_new(:http1, conn, status, headers) when status != 101 do
+    error = %UpgradeFailureError{status_code: status, headers: headers}
+    {:error, conn, error}
   end
 
   defp do_new(:http1, conn, _status, response_headers) do
@@ -352,8 +353,9 @@ defmodule Mint.WebSocket do
     end
   end
 
-  defp do_new(:http2, conn, _status, _response_headers) do
-    {:error, conn, %WebSocketError{reason: :connection_not_upgraded}}
+  defp do_new(:http2, conn, status, headers) do
+    error = %UpgradeFailureError{status_code: status, headers: headers}
+    {:error, conn, error}
   end
 
   @doc """

lib/mint/web_socket/upgrade_failure_error.ex

@@ -0,0 +1,14 @@
+defmodule Mint.WebSocket.UpgradeFailureError do
+  @moduledoc """
+  An error representing a failure to upgrade protocols from HTTP to WebSocket
+  """
+
+  defexception [:status_code, :headers]
+
+  def message(%__MODULE__{} = error) do
+    """
+    Could not upgrade from HTTP to WebSocket. The server returned status code #{error.status_code} with headers:
+    #{inspect(error.headers)}
+    """
+  end
+end

lib/mint/web_socket_error.ex

@@ -9,7 +9,6 @@ defmodule Mint.WebSocketError do
   reason_type =
     quote do
       :extended_connect_disabled
-      | :connection_not_upgraded
       | :payload_too_large
       | {:extension_not_negotiated, Mint.WebSocket.Extension.t()}
     end
@@ -27,10 +26,6 @@ defmodule Mint.WebSocketError do
     "extended CONNECT method not enabled"
   end
 
-  defp format_reason(:connection_not_upgraded) do
-    "connection not upgraded by remote"
-  end
-
   defp format_reason(:payload_too_large) do
     "frame payload cannot exceed 9,223,372,036,854,775,807 bytes"
   end