A Haskell client for the NATS messaging system. See https://nats.io for general information and documentation.

1) The current version of this library does not yet support TLS.

2) The current version of this library does not yet support authorization tokens (but support user names and passwords in the URI strings).

This section gives a simple messaging example using this library. The example requires the presence of a NATS server, running on localhost using the default port 4222. If other host or port, adapt the example.

{-# LANGUAGE OverloadedStrings #-}
module Main
   ( main
   ) where

import Network.Nats
import Text.Printf

main :: IO ()
main =
   withNats defaultSettings ["nats://localhost"] $ \nats -> do

       -- Subscribe to the topic "foo".
       (s, q) <- subscribe nats "foo" Nothing

       -- Publish to topic "foo", do not request a reply.
       publish nats "foo" Nothing "Some payload"

       -- Wait for a message, print the message's payload
       msg <- nextMsg q
       printf "Received %s\n" (show $ payload msg)

       -- Unsubscribe from topic "foo".
       unsubscribe nats s Nothing

Beside from the subscription mode where messages, synchronously, are fetched from a queue there is also an asynchronous mode where each request is handled immediately in their own thread.

{-# LANGUAGE OverloadedStrings #-}
module Main
   ( main
   ) where

import Control.Monad
import Data.Maybe
import Network.Nats
import Text.Printf

main :: IO ()
main =
   withNats defaultSettings ["nats://localhost"] $ \nats -> do
      
       -- A simple - asynchronous - help service that will answer
       -- requesters that give a reply topic with "I can help".
       s1 <- subscribeAsync nats "help" Nothing $ \msg -> do
           printf "Help service received: %s\n" (show $ payload msg)
           when (isJust $ replyTo msg) $
               publish nats (fromJust $ replyTo msg) Nothing "I can help"

       -- Subscribe to help replies.
       (s2, q) <- subscribe nats "help.reply" Nothing

       -- Request help.
       publish nats "help" (Just "help.reply") "Please ..."

       -- Wait for reply.
       msg <- nextMsg q
       printf "Received: %s\n" (show $ payload msg)

       -- Unsubscribe.
       unsubscribe nats s1 Nothing
       unsubscribe nats s2 Nothing

In the example above there's a common request pattern. Sending a message to a topic, requesting a reply, subscribing to the reply topic, receiving the reply message and then unsubscribe from the reply topic.

This pattern can be handled more simply using the request function.

{-# LANGUAGE OverloadedStrings #-}
module Main
   ( main
   ) where

import Control.Monad
import Data.Maybe
import Network.Nats
import Text.Printf

main :: IO ()
main =
   withNats defaultSettings ["nats://localhost"] $ \nats -> do

       -- A simple - asynchronous - help service that will answer
       -- requesters that give a reply topic with "I can help".
       s <- subscribeAsync nats "help" Nothing $ \msg -> do
           printf "Help service received: %s\n" (show $ payload msg)
           when (isJust $ replyTo msg) $
               publish nats (fromJust $ replyTo msg) Nothing "I can help"

       -- Request help.
       msg <- request nats "help" "Please ..."
       printf "Received: %s\n" (show $ payload msg)

       -- Unsubscribing the help service only.
       unsubscribe nats s Nothing

Topic structure is tree like similar to file systems, or the Haskell module structure, and components in the tree is separated by dots. A subscriber of a topic can use wildcards to specify patterns.

{-# LANGUAGE OverloadedStrings #-}
module Main
   ( main
   ) where

import Control.Monad
import Data.Maybe
import Network.Nats
import Text.Printf

main :: IO ()
main =
   withNats defaultSettings ["nats://localhost"] $ \nats -> do

       -- "*" matches any token, at any level of the subject.
       (_, queue1) <- subscribe nats "foo.*.baz" Nothing
       (_, queue2) <- subscribe nats "foo.bar.*" Nothing

       -- ">" matches any length of the tail of the subject, and can
       -- only be the last token.
       (_, queue3) <- subscribe nats "foo.>" Nothing

       -- This publishing matches all the above.
       publish nats "foo.bar.baz" Nothing "Hello world"

       -- Show that the message showed up on all queues.
       forM_ [queue1, queue2, queue3] $ \queue -> do
           msg <- nextMsg queue
           printf "Received: %s\n" (show $ payload msg)