gnat v0.4.0 Gnat
Link to this section Summary
Functions
Ping the NATS server
Publish a message
Send a request and listen for a response synchronously
Starts a connection to a nats broker
Gracefull shuts down a connection
Subscribe to a topic
Unsubscribe from a topic
Link to this section Types
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)
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")
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
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]
.
Gracefull shuts down a connection
{:ok, gnat} = Gnat.start_link()
:ok = Gnat.stop(gnat)
sub(GenServer.server, pid, String.t, keyword) :: {:ok, non_neg_integer}
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
unsub(GenServer.server, non_neg_integer, keyword) :: :ok
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)