Mint.WebSocket - (unofficial) WebSocket support for Mint 🌱

the-mikedavis

Mint.WebSocket (github) (hex) is a library built on the awesome Mint (github) (hex) functional HTTP client.

Mint.WebSocket extends Mint’s process-less architecture with a handful of functions for upgrading connections to the WebSocket protocol and encoding and decoding WebSocket frames. For example, we can send and receive some frames from an echo WebSocket server:

# see https://websocket.org/echo.html
{:ok, conn} = Mint.HTTP.connect(:https, "echo.websocket.org", 443)

{:ok, conn, ref} = Mint.WebSocket.upgrade(conn, "/", [])

message = receive(do: (message -> message))
{:ok, conn, [{:status, ^ref, status}, {:headers, ^ref, resp_headers}, {:done, ^ref}]} =
  Mint.HTTP.stream(conn, message)
{:ok, conn, websocket} = Mint.WebSocket.new(conn, ref, status, resp_headers)

{:ok, websocket, data} =
  Mint.WebSocket.encode(websocket, {:text, "Rock it with Mint.WebSocket"})
{:ok, conn} = Mint.HTTP.stream_request_body(conn, ref, data)

message = receive(do: (message -> message))
{:ok, conn, [{:data, ^ref, data}]} = Mint.HTTP.stream(conn, message)
{:ok, websocket, [{:text, "Rock it with Mint.WebSocket"}]} =
  Mint.WebSocket.decode(websocket, data)

{:ok, websocket, data} = Mint.WebSocket.encode(websocket, :close)
{:ok, conn} = Mint.HTTP.stream_request_body(conn, ref, data)

message = receive(do: (message -> message))
{:ok, conn, [{:data, ^ref, data}]} = Mint.HTTP.stream(conn, message)
{:ok, websocket, [{:close, 1_000, ""}]} =
  Mint.WebSocket.decode(websocket, data)

Mint.HTTP.close(conn)

Features:

HTTP/1 and HTTP/2 support through the same API
- although HTTP/2 WebSocket support is currently very limited among server frameworks
support for Extensions
- the popular “permessage-deflate” extension is included in the library
conformance checks with the Autobahn|Testsuite are built in to the CI
performance is roughly on par with :gun (Autobahn|Testsuite comparison)

10 comments

#library #websockets #mint

24 2459 10

2023-09-17 11:36:48 UTC

Showing Posts 1 to 10

Show Best Posts
Show All (oldest first)
Show All (newest first)

the-mikedavis

v1.0.0 was just released!

Since the last update, the API has been refactored to depend cleanly on Mint so that Mint.WebSocket should be future-proof for new Mint releases. We’ve also been using Mint.WebSocket extensively in production over the last (almost) year. And when I say extensively, I mean extensively: my metrics say that in the last week we made nearly one million connections with Mint.WebSocket!

Post #1

stevensonmt

This looks cool. Pros/Cons vs Phoenix?

Post #2

the-mikedavis

Mint.WebSocket is a WebSocket client so you could use it to, for example, connect to a cowboy server or a Phoenix.Channel (Slipstream actually uses Mint.WebSocket under the hood). In fact, Phoenix itself recently switched to using Mint.WebSocket to test Phoenix.Channels (see here).

Post #3

ycastor

Ohhhhhh nice! I’m using Mint and i’ll need that for WebSocket communications for my database driver, nice work!

Post #4

thojanssens1

Thank you!

We also have finch built on top of mint
and req built on top of finch

How would one use WebSockets when depending on any of those two other libs?

Post #5

the-mikedavis

Finch and Req only do HTTP for now and I’m not sure if it’s in scope for those projects to add WebSocket support. Since the dependencies are compatible, you could use Mint.WebSocket in any project that already has Mint by adding it to your dependencies:

# mix.exs
def deps do
  [
    # ...
    {:mint, "~> 1.4"},
    {:mint_web_socket, "~> 1.0"}
  ]
end

and then using Mint.WebSocket directly. There’s an example WebSocket client implementation as a GenServer you can use for reference here. A high-level WebSocket client that wraps Mint.WebSocket like Finch wraps Mint would be pretty cool some day

Post #6

thojanssens1

What would also be nice is to have a similar lib for SSE Server Sent Events. Which seem to be the future with http2 support.

Post #7

bfolkens

We started using this in production last month and it’s significantly faster than WebSockex. I’ll try to run some more formal perf tests when I get a chance.

Post #8