gnat v1.0.0 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
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
message()
message() :: %{
topic: String.t(),
body: String.t(),
sid: non_neg_integer(),
reply_to: String.t()
}
message() :: %{ topic: String.t(), body: String.t(), sid: non_neg_integer(), reply_to: String.t() }
Link to this section Functions
active_subscriptions(pid)
active_subscriptions(GenServer.server()) :: {:ok, non_neg_integer()}
active_subscriptions(GenServer.server()) :: {:ok, non_neg_integer()}
get the number of active subscriptions
child_spec(init_arg)
Returns a specification to start this module under a supervisor.
See Supervisor
.
ping(pid)
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(pid, topic, message, opts \\ [])
pub(GenServer.server(), String.t(), binary(), keyword()) :: :ok
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(pid, topic, body, opts \\ [])
request(GenServer.server(), String.t(), binary(), keyword()) ::
{:ok, message()} | {:error, :timeout}
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(gnat, "i_can_haz_cheezburger", "plZZZZ?!?!?") do
{:ok, %{body: delicious_cheezburger}} -> :yum
{:error, :timeout} -> :sad_cat
end
start_link(connection_settings \\ %{}, opts \\ [])
start_link(map(), keyword()) :: GenServer.on_start()
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]
.
stop(pid)
stop(GenServer.server()) :: :ok
stop(GenServer.server()) :: :ok
Gracefull shuts down a connection
{:ok, gnat} = Gnat.start_link()
:ok = Gnat.stop(gnat)
sub(pid, subscriber, topic, opts \\ [])
sub(GenServer.server(), pid(), String.t(), keyword()) ::
{:ok, non_neg_integer()} | {:ok, String.t()} | {:error, String.t()}
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
unsub(pid, sid, opts \\ [])
unsub(GenServer.server(), non_neg_integer() | String.t(), keyword()) :: :ok
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)