gnat v0.5.1 Gnat

Link to this section Summary

Functions

get the number of active subscriptions

Returns a specification to start this module under a supervisor

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 Types

Link to this type message()
message() :: %{topic: String.t(), body: String.t(), reply_to: String.t()}

Link to this section Functions

Link to this function active_subscriptions(pid)
active_subscriptions(GenServer.server()) :: {:ok, non_neg_integer()}

get the number of active subscriptions

Link to this function child_spec(arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

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 \\ [])
pub(GenServer.server(), String.t(), binary(), keyword()) :: :ok

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 \\ [])
request(GenServer.server(), String.t(), binary(), keyword()) ::
  {:ok, message()} | {:error, :timeout}

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 \\ [])
start_link(map(), keyword()) :: GenServer.on_start()

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].

Link to this function stop(pid)
stop(GenServer.server()) :: :ok

Gracefull shuts down a connection

{:ok, gnat} = Gnat.start_link()
:ok = Gnat.stop(gnat)
Link to this function sub(pid, subscriber, topic, opts \\ [])
sub(GenServer.server(), pid(), String.t(), keyword()) ::
  {:ok, non_neg_integer()} | {:ok, String.t()} | {:error, String.t()}

Subscribe to a topic

Supported options:

  • queue_group: a string that identifies which queue group you want to join

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)

{: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 \\ [])
unsub(GenServer.server(), non_neg_integer() | String.t(), keyword()) :: :ok

Unsubscribe from a topic

Supported options:

  • max_messages: number of messages to be received before automatically unsubscribed

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)