Alternative Websocket Effects Manager for Elm

Websocket Effects Manager for Elm that works with BOTH front-end (browser) and back-end (node) programs. It allows for more sophisticated higher-level protocols than the default Websocket provided by Elm. It provides a message when the connection is lost allowing clients to employ their own reconnection strategy.

For example, when connecting to stateful back-end services, the client may need to re-authenticate or re-subscribe to that service.

Install

You'll need Grove.

grove install panosoft/elm-websocket-client

Node modules in Browser

This Effects Manager uses native code that relies on node-based code. Therefore, when this Effects Manager is used the browser, some package manager is required. Webpack is used in the Test application.

Build Test Apps

Browser

The buildBrowser.sh (and aBuildBrowser.sh) file(s) contains the Webpack command to build the test Browser program.

The output will be in a build directory. This file will be included by the Test/Browser/index.html file.

Node

The buildNode.sh (and aBuildNode.sh) file(s) contains the build command to build the test Node program.

API

Commands

Connect to a Websocket Server

This must be done before any other commands are run.

Connections are maintained by the Effect Manager State and are referenced via urls.

connect : ConnectErrorTagger msg -> ConnectTagger msg -> Url -> Bool -> Cmd msg
connect errorTagger tagger url rejectUnauthorized

Usage

connect ConnectError Connect "wss://echo.websocket.org" True

• ConnectError and Connect are your application's messages to handle the different scenarios.
• wss://echo.websocket.org is the URL to the websocket server
• rejectUnauthorized should be True unless testing with self-signed certificates (do not set to False in production!!!) This parameter is ignored if you're running in the Browser.

Send a message to the Websocket Server

Send a message to a specified URL. (A connection must already exist)

send : SendErrorTagger msg -> SendTagger msg -> Url -> String -> Cmd msg
send errorTagger tagger url message

Usage

send SendError Sent "wss://echo.websocket.org" "a string message"

• SendError and Sent are your application's messages to handle the different scenarios
• wss://echo.websocket.org is the URL to the websocket server
• a string message is the message to send

Disconnect from a Websocket Server

When a connection is no longer needed, it can be disconnected.

disconnect : DisconnectErrorTagger msg -> DisconnectTagger msg -> Url -> Cmd msg
disconnect errorTagger tagger url

Usage

disconnect ErrorDisconnect SuccessDisconnect "wss://echo.websocket.org"

• ErrorDisconnect and SuccessDisconnect are your application's messages to handle the different scenarios
• wss://echo.websocket.org is the URL to the websocket server

Subscriptions

Listen for messages and events from a Websocket Server

Listen for messages and events from a specified URL (A connection must already exist)

listen : ListenErrorTagger msg -> MessageTagger msg -> ConnectionClosedTagger msg -> Url -> Sub msg
listen errorTagger messageTagger connectionClosedTagger url =

Usage

listen ListenError Message ConnectionLost "wss://echo.websocket.org"

• ListenError is your application's message to handle an error in listening
• Message is your application's message to handle received messages
• ConnectionLost is your application's message to handle when the server closes it's connection
• wss://echo.websocket.org is the URL to the websocket server

Messages

ConnectErrorTagger

Error when connecting.

type alias ConnectErrorTagger msg =
    ( Url, ( ConnectErrorCode, ErrorMessage ) ) -> msg

ConnectErrorCode values are defined in the Websocket Protocol.

Usage

ConnectError ( url, (errorCode, errorMessage) ) ->
	let
		l =
			Debug.log "ConnectError" ( url, (errorCode, errorMessage) )
	in
		model ! []

ConnectTagger

Successful connection.

type alias ConnectTagger msg =
    Url -> msg

Usage

Connect url ->
	let
		l =
			Debug.log "Connect" url
	in
		{ model | connected = True } ! []

SendErrorTagger

Error attempting to send.

type alias SendErrorTagger msg =
    ( Url, Message, ErrorMessage ) -> msg

Usage

SendError ( url, message, error ) ->
	let
		l =
			Debug.log "SendError" ( url, message, error )
	in
		model ! []

SendTagger

Successful send.

type alias SendTagger msg =
    ( Url, Message ) -> msg

Usage

Sent ( url, message ) ->
	let
		l =
			Debug.log "Sent" ( url, message )
	in
		model ! []

DisconnectErrorTagger

Error when disconnecting.

type alias DisconnectErrorTagger msg =
    ( Url, ErrorMessage ) -> msg

Usage

DisconnectError ( url, error ) ->
	let
		l =
			Debug.log "DisconnectError" ( url, error )
	in
		model ! []

DisconnectTagger

Successful disconnect.

type alias DisconnectTagger msg =
    Url -> msg

Usage

Disconnect url ->
	let
		l =
			Debug.log "Disconnect" url
	in
		model ! []

ListenErrorTagger

Error when attempting to listen.

type alias ListenErrorTagger msg =
    ( Url, ErrorMessage ) -> msg

Usage

ListenError ( url, error ) ->
	let
		l =
			Debug.log "ListenError" ( url, error )
	in
		{ model | listenError = True } ! []

MessageTagger

Message received from server.

type alias MessageTagger msg =
    ( Url, Message ) -> msg

Usage

Message ( url, message ) ->
	let
		l =
			Debug.log "Message" ( url, message )
	in
		model ! []

ConnectionClosedTagger

Server closed the connection.

type alias ConnectionClosedTagger msg =
    (Url, ConnectErrorCode, ErrorMessage) -> msg

Usage

ConnectionLost (url, errorCode, errorMessage) ->
	let
		l =
			Debug.log "ConnectionLost" (url, errorCode, errorMessage)
	in
		{ model | connected = False } ! []