NATS is a simple, secure and performant communications system for digital systems, services and devices.
This library is a pure Elm implementation of the NATS client protocol on top a websocket.
A running nats-server, with websockets enabled (see WebSocket Configuration Example)
go install github.com/nats-io/nats-server/v2@latest
cd examples/string_socket
nats-server -c server.conf
cd examples/string_socket
elm-go -- src/Main.elm -o main.js
NATS subscriptions handling is a stateful business, which is all done by the Nats module. You need to wire it into your application.
-
Import the Nats module
import Nats import Nats.Config import Nats.Effect import Nats.PortsAPI import Nats.Protocol import Nats.Socket import Nats.Sub
-
Add a global nats state, on your top-level application model, or Shared model. At this point you need to choose between Bytes and String sockets. The String socket will only be able to exchange String messages with the server.
Using protobuf requires a Bytes socket.
type alias Model = { nats: Nats.State String Msg -- ... }
-
Add a NatsMsg tag to your Msg type:
type Msg = ... | NatsMsg Nats.Msg
-
Setup the ports and the configuration, with a message type consistent with your nats state:
port natsSend : Nats.PortsAPI.Send String msg port natsReceive : Nats.PortsAPI.Receive String msg natsConfig : Nats.Config String String Msg natsConfig = Nats.Config.string NatsMsg { send = natsSend , receive = natsReceive }
-
Initialize the State.
init { flags | now : Int } = { nats = Nats.init now (Time.millisToPosix now) }
-
Connect nats to the ports :
subscriptions : Model -> Sub Msg subscriptions = Nats.subscriptions natsConfig model.nats
-
Define the top-level nats subscriptions:
natsSubscriptions : Model -> Nats.Sub natsSubscriptions model = Nats.Sub.none
-
Have your update function(s) return nats effect along with the regular Cmd, and wrap it to handle them:
wrappedUpdate : Msg -> Model -> ( Model, Cmd Msg ) wrappedUpdate msg model = let ( newModel, natsEffect, cmd ) = update msg model ( nats, natsCmd ) = Nats.applyEffectAndSub natsConfig natsEffect (natsSubscriptions model) newModel.nats in ( { newModel | nats = nats } , Cmd.batch [ cmd, natsCmd ] ) update : Msg -> Model -> ( Model, Nats.Effect Msg, Cmd Msg) update msg model = ( model, Nats.Effect.none, Cmd.none )
-
At last, setup the ports on the javascript side, by using the 'js/natsports.js' file:
<html> <head> <meta charset="UTF-8"> <script src="main.js"></script> <script src="natsports.js"></script> </head> <body> <script> var app = Elm.Main.init( { flags: { now: Date.now() } } ); setupNatsPorts(app); </script> </body> </html>
Connect a socket is done with simple subscription:
natsSubscriptions : Model -> Nats.Sub
natsSubscriptions model =
Nats.connect
( Nats.Socket.connectOptions
|> Nats.Socket.withUserPass "user" "password"
)
( Nats.Socket.new "0" "ws://localhost:8087" )The socket definition and connection options will generally be saved on the model
In update, use publish to generate the right Effect:
( model
, Nats.publish "subject1" "Hello world!"
, Cmd.none
)
-
Define a Msg tag for receiving messages
type Msg = ReceiveSubject1 (Nats.Protocol.Message String)
-
Add the subscriptions to the "natsSubscriptions" function:
natsSubscriptions model = Nats.subscribe "subject1" ReceiveSubject1
-
Define a Msg tag for receiving the response
type Msg = ReceiveResponse (Result Nats.Errors.Timeout (Nats.Protocol.Message String))
-
Send a request from your update function
( model , Nats.request "subject1" "message" ReceiveResponse , Cmd.none )