update

phoenix/deps/websock_adapter/README.md

@@ -0,0 +1,102 @@
+# WebSockAdapter
+
+[![Build Status](https://github.com/phoenixframework/websock_adapter/workflows/Elixir%20CI/badge.svg)](https://github.com/phoenixframework/websock_adapter/actions)
+[![Docs](https://img.shields.io/badge/api-docs-green.svg?style=flat)](https://hexdocs.pm/websock_adapter)
+[![Hex.pm](https://img.shields.io/hexpm/v/websock_adapter.svg?style=flat&color=blue)](https://hex.pm/packages/websock_adapter)
+
+WebSockAdapter is a library of adapters from common Web Servers to the
+`WebSock` specification. WebSockAdapter currently supports
+[Bandit](https://github.com/mtrudel/bandit) and
+[Cowboy](https://github.com/ninenines/cowboy).
+
+For details on the `WebSock` specification, consult the
+[WebSock](https://hexdocs.pm/websock) documentation.
+
+## Usage
+
+WebSockAdapter makes it easy to upgrade Plug connections to WebSock connections.
+Here's a simple example:
+
+```elixir
+defmodule EchoServer do
+  def init(args) do
+    {:ok, []}
+  end
+
+  def handle_in({"ping", [opcode: :text]}, state) do
+    {:reply, :ok, {:text, "pong"}, state}
+  end
+end
+
+defmodule MyPlug do
+  use Plug.Router
+
+  plug Plug.Logger
+  plug :match
+  plug :dispatch
+
+  get "/" do
+    # Provide the user with some useful instructions to copy & paste into their inspector
+    send_resp(conn, 200, """
+    Use the JavaScript console to interact using websockets
+
+    sock  = new WebSocket("ws://localhost:4000/websocket")
+    sock.addEventListener("message", console.log)
+    sock.addEventListener("open", () => sock.send("ping"))
+    """)
+  end
+
+  get "/websocket" do
+    conn
+    |> WebSockAdapter.upgrade(EchoServer, [], timeout: 60_000)
+    |> halt()
+  end
+
+  match _ do
+    send_resp(conn, 404, "not found")
+  end
+end
+```
+
+This simple example illustrates many of the useful features of WebSock / WebSockAdapters:
+
+* Implementing a WebSocket server is a single module, and looks & acts much like
+  a GenServer does
+* It's easy to pass state from the `WebSockAdapter.upgrade/3`
+  call & have it show up in your WebSock callbacks
+* Upgrades are handled as a plain Plug call. You are able to route requests to
+  your upgrade endpoint using all of the power of the Plug API
+
+If you're looking for more detail, Benjamin Milde has a [great blog
+post](https://kobrakai.de/kolumne/bare-websockets) that goes a bit deeper than
+the simple example above.
+
+## Upgrade Validation
+
+Since `0.5.5`, WebSockAdapter validates requests made via
+`WebSockAdapter.upgrade/3` (this was and continues to also be done by the
+underlying web server, but since the server's validation occurs after the
+`Plug.call/2` lifecycle completes it's difficult to meaningfully handle such
+errors). This validation examines the request for conformance to the clauses
+laid out in RFC6455§4.2, as well as RFC8441§5 for HTTP/2 connections. Requests
+which do not satisfy the requirements laid out in those specifications will
+result in a `WebSockAdapter.UpgradeError` being raised, containing
+details of the reason for the failure
+
+## Installation
+
+The websock_adapter package can be installed by adding `websock_adapter` to your list of dependencies in `mix.exs`:
+
+```elixir
+def deps do
+  [
+    {:websock_adapter, "~> 0.5"}
+  ]
+end
+```
+
+Documentation can be found at <https://hexdocs.pm/websock_adapter>.
+
+## License
+
+MIT