Gaoxy WebSockAdapter

gaoxy_websock_adapter is the Gaoxy distribution of Phoenix's WebSockAdapter. It connects WebSockAdapter.upgrade/4 to Gaoxy.PlugAdapter and validates native HTTP/2 and HTTP/3 WebSocket extended CONNECT requests, including Phoenix requests whose method is temporarily presented as GET.

Use this package with gaoxy_http when serving Phoenix Channels, LiveView or a Plug that upgrades connections to WebSocket. Its public modules and OTP application keep the upstream name WebSockAdapter / :websock_adapter. Its package version follows Gaoxy, currently 0.11.0; the upstream source base is WebSockAdapter 0.6.0.

Installation

Add these entries to your application's mix.exs dependencies:

{:gaoxy_http, "~> 0.11.0"},
{:websock_adapter, "~> 0.11.0", hex: :gaoxy_websock_adapter, override: true}

Then run mix deps.get. The override makes Phoenix's existing :websock_adapter dependency resolve to this distribution. Keep the override while using Gaoxy; selecting the canonical upstream package removes Gaoxy dispatch and native H2/H3 validation.

Phoenix configuration

Replace the explicit Bandit dependency with the dependencies above and select Gaoxy in config/config.exs:

config :my_app, MyAppWeb.Endpoint,
  adapter: Gaoxy.PhoenixAdapter

For local development, configure config/dev.exs:

config :my_app, MyAppWeb.Endpoint,
  http: [ip: {127, 0, 0, 1}, port: 4000],
  server: true

Keep the Endpoint under your application's supervisor and start it with mix phx.server. Phoenix continues to own socket declarations, authentication, Origin checks and LiveView settings. Ordinary H1 WebSocket upgrades use your existing socket paths.

For native WebSocket over HTTP/2, add exact paths at the Endpoint level and enable extended CONNECT on the HTTPS listener:

config :my_app, MyAppWeb.Endpoint,
  websocket_paths: ["/live/websocket", "/socket/websocket"],
  https: [
    ip: {127, 0, 0, 1},
    port: 4040,
    certfile: "/absolute/path/to/cert.pem",
    keyfile: "/absolute/path/to/key.pem",
    extended_connect: true
  ]

The paths must match sockets actually declared by your Endpoint; include the /websocket suffix. These settings enable the server capability. The client selects the WebSocket transport. HTTP/3 uses a separate optional Gaoxy.HTTP.HTTP3 service and external Endpoint mount.

See the complete Phoenix and Bandit migration guide for production configuration, development code reload, supported listener options and HTTP/3 setup.

Upgrade a Plug connection

Define a WebSock handler and route an upgrade through your Plug:

defmodule MyApp.EchoSocket do
  @behaviour WebSock

  def init(state), do: {:ok, state}

  def handle_in({data, [opcode: opcode]}, state) when opcode in [:text, :binary],
    do: {:reply, :ok, {opcode, data}, state}

  def handle_info(_message, state), do: {:ok, state}
end

defmodule MyApp.Router do
  use Plug.Router

  plug :match
  plug :dispatch

  get "/websocket" do
    conn
    |> WebSockAdapter.upgrade(MyApp.EchoSocket, nil, timeout: 60_000)
    |> halt()
  end

  match _ do
    send_resp(conn, 404, "Not found")
  end
end

Supervise {Gaoxy.HTTP, plug: {MyApp.Router, []}, port: 4000} and connect a WebSocket client to ws://localhost:4000/websocket. This example serves H1; native H2/H3 requires the protocol-specific listener and routing setup in the HTTP guide.

Early upgrade validation is enabled by default. Leave it enabled. Gaoxy also validates the handshake and owns transport/lifecycle enforcement. WebSocket compression is unsupported; use compress: false when an existing socket explicitly enabled it.

Upstream source and license

The source checkout preserves the upstream README.md unchanged. Hex staging uses this Gaoxy guide as README.md and retains the upstream document as README.upstream.md. The package also includes GAOXY.md, SOURCE.json, gaoxy.patch, the upstream changelog and licenses. SOURCE.json describes the vendored snapshot paths; its README.md hash refers to the retained upstream document.

See snapshot provenance and upstream WebSockAdapter. MIT; upstream LICENSE is retained and Gaoxy's license is included as LICENSE.gaoxy in the Hex package.