Deprecated: use ghcjs-base's native websockets

Latest on Hackage:

This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow to host generated Haddocks.

MIT licensed and maintained by Justin Le


Join the chat at

ghcjs-websockets aims to provide a clean, idiomatic, efficient, low-level, out-of-your-way, bare bones, concurrency-aware interface with minimal abstractions over the Javascript Websockets API, inspired by common Haskell idioms found in libraries like io-streams and the server-side websockets library, targeting compilation to Javascript with ghcjs.

The interface abstracts websockets as simple IO/file handles, with additional access to the natively "typed" (text vs binary) nature of the Javascript Websockets API. There are also convenience functions to directly decode serialized data (serialized with binary) sent through channels.

The library is mostly intended to be a low-level FFI library, with the hopes that other, more advanced libraries maybe build on the low-level FFI bindings in order to provide more advanced and powerful abstractions. Most design decisions were made with the intent of keeping things as simple as possible in order for future libraries to abstract over it.

Most of the necessary functionality is in hopefully in JavaScript.WebSockets; more of the low-level API is exposed in JavaScript.WebSockets.Internal if you need it for library construction.

Documenation is online on github pages.


import Data.Text (unpack)

-- A simple echo client, echoing all incoming text data
main :: IO ()
main = withUrl "ws://" $ \conn ->
    forever $ do
        t <- receiveText conn
        putStrLn (unpack t)
        sendText conn t

The above code will attempt to interpret all incoming data as UTF8-encoded Text, and throw away data that does not.

conn is a Connection, which encapsulates a websocket channel.

You can also do the same thing to interpret all incoming data as any instance of Binary --- say, Ints:

-- A simple client waiting for connections and outputting the running sum
main :: IO ()
main = withUrl "ws://" (runningSum 0)

runningSum :: Int -> Connection -> IO ()
runningSum n conn = do
    i <- receiveData conn
    print (n + i)
    runningSum (n + i) conn

receiveData will block until the Connection receives data that is decodable as whatever type you expect, and will throw away all nondecodable data (including Text data).

The receive function is provided as an over-indulgent layer of abstraction where you can receive both Text and instances of Binary with the same function using typeclass magic --- for the examples above, you could use receive in place of both receiveText and receiveData.

send works the same way for sendText and sendData.

If you want to, you can access the incoming data directly using the SocketMsg sum type, which exposes either a Text or a lazy ByteString:

import Data.Text (unpack, append)
import qualified Data.ByteString.Base64.Lazy as B64

main :: IO ()
main = withUrl "ws://" $ \conn ->
    forever $ do
        msg <- receiveMessage
        putStrLn $ case msg of
            SocketMsgText t ->
                unpack $ append "Received text: " t
            SocketMsgData d ->
                "Received data: " ++ show (B64.encode d)

You can talk to multiple connections by nesting withUrl:

-- Act as a relay between two servers
main :: IO ()
main =  withUrl "ws://" $ \conn1 ->
        withUrl "ws://" $ \conn2 ->
            forever $ do
                msg <- receiveMessage conn1
                sendMessage conn2 msg

And also alternatively, you can manually open and close connections:

-- Act as a relay between two servers
main :: IO ()
main = do
    conn1 <- openConnection "ws://"
    conn2 <- openConnection "ws://"
    forever $ do
        msg <- receiveMessage conn1
        sendMessage conn2 msg
    closeConnection conn2
    closeConnection conn1

receiveMessage and its varieties will all throw an exception if the connection closes while they're waiting or if you attempt to receive on a closed connection. You can handle these with mechanisms from Control.Exception, or you can use their "maybe"-family counterparts, receiveMessageMaybe, etc., who will return results in Just on a success, or return a Nothing if the connection is closed or if receiving on a closed connection.

You can use also connectionClosed :: Connection -> IO Bool to check if the given Connection object is closed (or connectionCloseReason to see why).

When closing connections, there might be some messages that were received by the socket but never processed on the Haskell side with a receive method. These will normally be deleted; however, you can use closeConnectionLeftovers or withUrlLeftovers to grab a list of the raw SocketMsgs remaining after closing.

Issues and Roadmap

As of now, there are still some exceptions that might be thrown by the Javascript websockets API that are not explicitly handled by the library. For the most part, things are usable and asynchronous exceptions (in Haskell) should all be handled well at this point. There are also some small aspects of the websockets API that aren't yet accessible through the library.

Copyright (c) Justin Le 2015


  • Fixing withURL blocking when there is a javascript error on connection. (Thanks to sztupi)

  • Fixed bug on double mutex acquisition for connectionClosed.

DEPRECATED: Please use!

  • Added CPP an cabal file flags necessary to enable building on (normal) GHC, for hackage and usage with hybrid projects.

DEPRECATED: Please use!

  • Lowered bounds on text dependency.
  • Added and to extra source dependecy fields, to count them in the cabal package.

DEPRECATED: Please use!

  • Fixed the "other-modules" cabal file field to include non-exported but important modules.

DEPRECATED: Please use!

  • First official release. API more or less stabilized. Library is more or less stable, but there are still some extra aspects of the javascript websockets API to hook onto for more power/information, and some javascript errors to be handled on edge cases.

comments powered byDisqus