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

Your Libraries & OS Mentoring Libraries
,
1

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)
24 Likes
2

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!

5 Likes
3

This looks cool. Pros/Cons vs Phoenix?

4

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).

4 Likes
5

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

1 Like
6

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?

1 Like
7

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 :smile:

2 Likes
8

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.

9

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.

1 Like
10

Extracted the basics today, it’s up now at https://hex.pm/packages/wind. Any feedback welcome, of course. Will add more soon.

3 Likes
11

I am currently working on a WebSocket client which is similar to WebSockex but built atop Mint ecosystem: GitHub - bunopnu/fresh: WebSocket client for Elixir, built atop the Mint ecosystem 🌱

Waiting for feedbacks… :slight_smile:

1 Like