gnat v0.3.3 Gnat

Link to this section Summary

Functions

Ping the NATS server

Send a request and listen for a response synchronously

Starts a connection to a nats broker

Gracefull shuts down a connection

Unsubscribe from a topic

Link to this section Functions

Ping the NATS server

This correlates to the PING command in the NATS protocol. If the NATS server responds with a PONG message this function will return :ok

{:ok, gnat} = Gnat.start_link()
:ok = Gnat.ping(gnat)
Link to this function pub(pid, topic, message, opts \\ [])

Publish a message

{:ok, gnat} = Gnat.start_link()
:ok = Gnat.pub(gnat, "characters", "Ron Swanson")

If you want to provide a reply address to receive a response you can pass it as an option. See request-response pattern.

{:ok, gnat} = Gnat.start_link()
:ok = Gnat.pub(gnat, "characters", "Star Lord", reply_to: "me")
Link to this function request(pid, topic, body, opts \\ [])

Send a request and listen for a response synchronously

Following the nats request-response pattern this function generates a one-time topic to receive replies and then sends a message to the provided topic.

Supported options:

  • receive_timeout: an integer number of milliseconds to wait for a response. Defaults to 60_000
{:ok, gnat} = Gnat.start_link()
case Gnat.request("i_can_haz_cheezburger", "plZZZZ?!?!?") do
  {:ok, %{body: delicious_cheezburger}} -> :yum
  {:error, :timeout} -> :sad_cat
end
Link to this function start_link(connection_settings \\ %{}, opts \\ [])

Starts a connection to a nats broker

{:ok, gnat} = Gnat.start_link(%{host: '127.0.0.1', port: 4222})
# if the server requires TLS you can start a connection with:
{:ok, gnat} = Gnat.start_link(%{host: '127.0.0.1', port: 4222, tls: true})
# if the server requires TLS and a client certificate you can start a connection with:
{:ok, gnat} = Gnat.start_link(%{tls: true, ssl_opts: [certfile: "client-cert.pem", keyfile: "client-key.pem"]})

You can also pass arbitrary SSL or TCP options in the tcp_opts and ssl_opts keys. If you pass custom TCP options please include :binary. Gnat uses binary matching to parse messages.

The final opts argument will be passed to the GenServer.start_link call so you can pass things like [name: :gnat_connection].

Gracefull shuts down a connection

{:ok, gnat} = Gnat.start_link()
:ok = Gnat.stop(gnat)
Link to this function sub(pid, subscriber, topic, opts \\ [])

Subscribe to a topic

By default each subscriber will receive a copy of every message on the topic. When a queue_group is supplied messages will be spread among the subscribers in the same group. (see nats queueing)

Supported options:

  • queue_group: a string that identifies which queue group you want to join
{:ok, gnat} = Gnat.start_link()
{:ok, subscription} = Gnat.sub(gnat, self(), "topic")
receive do
  {:msg, %{topic: "topic", body: body}} ->
    IO.puts "Received: #{body}"
end
Link to this function unsub(pid, sid, opts \\ [])

Unsubscribe from a topic

This correlates to the UNSUB command in the nats protocol. By default the unsubscribe is affected immediately, but an optional max_messages value can be provided which will allow max_messages to be received before affecting the unsubscribe. This is especially useful for request response patterns.

{:ok, gnat} = Gnat.start_link()
{:ok, subscription} = Gnat.sub(gnat, self(), "my_inbox")
:ok = Gnat.unsub(gnat, subscription)
# OR
:ok = Gnat.unsub(gnat, subscription, max_messages: 2)