nats (enats v1.1.2)

View Source

Summary

Functions

Connects to a NATS server or cluster using the specified options. This function supports the v1 options format, including a list of servers.

Connects to a NATS server or cluster using the specified server information and v0 options. Supports connecting to a single server or a list of servers.

Connects to a NATS server at the given host and port with specified v0 options.

Disconnects the client from the NATS server.

Dumps the current subscriptions for debugging purposes.

Creates an endpoint record for use within a service.

Flushes the pending messages to the NATS server.

Return true is the connection process is alive

Checks if the client is ready to send and receive messages.

Retrieves the remote peer address of the connection.

Publishes a message with no payload and default options to the specified subject.

Publishes a message with either no payload and specified options to the specified subject, or with the specified payload and default options to the specified subject.

Publishes a message with the specified payload and options to the specified subject.

Sends a request message and waits for a single reply.

Generates a random topic ID.

Registers a service with the NATS server.

Retrieves the server information received during connection.

Creates a service record for use with serve/2.

Sends a reply to a service request.

Sends a reply with headers to a service request.

Retrieves the local socket address of the connection.

Subscribes to the specified subject with default options.

Subscribes to the specified subject with the given options.

Unsubscribes from the specified subscription reference.

Unsubscribes from the specified subscription reference with options (e.g., max messages).

Types

conn()

-opaque conn()

endpoint()

-type endpoint() ::
          #{name := binary(), group_name => binary(), queue_group => binary(), metadata => map()}.

nats_host()

-type nats_host() :: inet:socket_address() | inet:hostname() | binary().

nats_server()

-type nats_server() ::
          #{scheme := binary(),
            host := nats_host(),
            port := non_neg_integer() | undefined,
            family := undefined | inet | inet6,
            preference := 0..65535,
            host := 0..65535,
            explicit := boolean()}.

nats_server_info()

-type nats_server_info() ::
          #{scheme => binary(),
            family => undefined | inet | inet6,
            host => nats_host(),
            port => non_neg_integer() | undefined}.

nats_server_opts()

-type nats_server_opts() ::
          #{scheme := binary(),
            family := undefined | inet | inet6,
            preference := 0..65535,
            order := 0..65535,
            explicit := boolean()}.

notify_fun()

-type notify_fun() ::
          fun((Sid :: sid(), Subject :: binary(), Payload :: binary(), MsgOpts :: map()) -> any()).

service()

-type service() :: #{name := binary(), version := binary(), description => binary(), metadata => map()}.

sid()

-opaque sid()

socket_opts()

-type socket_opts() ::
          #{netns => string(),
            netdev => binary(),
            rcvbuf => non_neg_integer(),
            sndbuf => non_neg_integer(),
            reuseaddr => boolean()}.

v0_opts()

-type v0_opts() ::
          #{socket_opts => socket_opts(),
            verbose => boolean(),
            pedantic => boolean(),
            tls_required => boolean(),
            tls_first => boolean(),
            tls_opts => [ssl:tls_client_option()],
            auth_required => optional | boolean(),
            auth_token => binary(),
            user => binary(),
            pass => binary(),
            nkey_seed => binary(),
            jwt => binary(),
            name => binary(),
            lang => binary(),
            version => binary(),
            headers => boolean(),
            no_responders => boolean(),
            buffer_size => -1 | non_neg_integer(),
            max_batch_size => non_neg_integer(),
            send_timeout => non_neg_integer()}.

v1_opts()

-type v1_opts() ::
          #{socket_opts => socket_opts(),
            verbose => boolean(),
            pedantic => boolean(),
            tls_required => boolean(),
            tls_first => boolean(),
            tls_opts => [ssl:tls_client_option()],
            auth_required => optional | boolean(),
            auth_token => binary(),
            user => binary(),
            pass => binary(),
            name => binary(),
            lang => binary(),
            version => binary(),
            headers => boolean(),
            no_responders => boolean(),
            buffer_size => -1 | non_neg_integer(),
            max_batch_size => non_neg_integer(),
            send_timeout => non_neg_integer(),
            stop_on_error => boolean(),
            default_explicit_host_preference => 0..65535,
            default_explicit_host_order => 0..65535,
            default_implicit_host_preference => 0..65535,
            default_implicit_host_order => 0..65535,
            servers => [nats_server_info()]}.

Functions

connect(Opts)

-spec connect(Opts :: v1_opts()) -> {ok, Conn :: conn()} | ignore | {error, Error :: term()}.

Connects to a NATS server or cluster using the specified options. This function supports the v1 options format, including a list of servers.

connect/2

-spec connect(Server :: nats_server_info(), Opts :: v0_opts()) ->
                 {ok, Conn :: conn()} | ignore | {error, Error :: term()};
             (Servers :: [nats_server_info()], Opts :: v0_opts()) ->
                 {ok, Conn :: conn()} | ignore | {error, Error :: term()};
             (Host :: nats_host(), Port :: inet:port_number()) ->
                 {ok, Conn :: conn()} | ignore | {error, Error :: term()}.

Connects to a NATS server or cluster using the specified server information and v0 options. Supports connecting to a single server or a list of servers.

connect(Host, Port, Opts)

-spec connect(Host :: nats_host(), Port :: inet:port_number(), Opts :: v0_opts()) ->
                 {ok, Conn :: conn()} | ignore | {error, Error :: term()}.

Connects to a NATS server at the given host and port with specified v0 options.

disconnect(Server)

-spec disconnect(Server :: conn()) -> ok | {error, timeout}.

Disconnects the client from the NATS server.

dump_subs(Server)

-spec dump_subs(Server :: conn()) -> list().

Dumps the current subscriptions for debugging purposes.

endpoint(EndpDesc, Function)

-spec endpoint(endpoint(), atom()) -> #endpoint{function :: term(), id :: term(), endpoint :: term()}.

Creates an endpoint record for use within a service.

flush(Server)

-spec flush(Server :: conn()) -> ok | {error, timeout}.

Flushes the pending messages to the NATS server.

is_alive(Server)

-spec is_alive(Server :: conn()) -> boolean().

Return true is the connection process is alive

is_ready(Server)

-spec is_ready(Server :: conn()) -> boolean() | {error, timeout | not_found}.

Checks if the client is ready to send and receive messages.

peername(Server)

-spec peername(Server :: conn()) -> {ok, map()} | {error, timeout | closed}.

Retrieves the remote peer address of the connection.

pub(Server, Subject)

-spec pub(Server :: conn(), Subject :: iodata()) -> ok | {error, timeout}.

Publishes a message with no payload and default options to the specified subject.

pub/3

-spec pub(Server :: conn(), Subject :: iodata(), Payload :: iodata()) -> ok | {error, timeout};
         (Server :: conn(), Subject :: iodata(), Opts :: map()) -> ok | {error, timeout}.

Publishes a message with either no payload and specified options to the specified subject, or with the specified payload and default options to the specified subject.

pub(Server, Subject, Payload, Opts)

-spec pub(Server :: conn(), Subject :: iodata(), Payload :: iodata(), Opts :: map()) ->
             ok | {error, timeout}.

Publishes a message with the specified payload and options to the specified subject.

request(Server, Subject, Payload, Opts)

-spec request(Server :: conn(), Subject :: iodata(), Payload :: iodata(), Opts :: map()) ->
                 {ok, {Payload :: iodata(), MsgOpts :: map()}} |
                 {error, timeout | not_ready | no_responders}.

Sends a request message and waits for a single reply.

rnd_topic_id()

-spec rnd_topic_id() -> binary().

Generates a random topic ID.

serve(Server, Service)

-spec serve(Server :: conn(),
            Service ::
                #svc{module :: term(),
                     state :: term(),
                     id :: term(),
                     service :: term(),
                     endpoints :: term(),
                     started :: term()}) ->
               ok | {error, timeout | not_ready}.

Registers a service with the NATS server.

server_info(Server)

-spec server_info(Server :: conn()) -> {ok, map()} | {error, timeout | closed}.

Retrieves the server information received during connection.

service(SvcDesc, EndpDesc, Module, State)

-spec service(service(),
              [#endpoint{function :: term(), id :: term(), endpoint :: term()}, ...],
              module(),
              any()) ->
                 #svc{module :: term(),
                      state :: term(),
                      id :: term(),
                      service :: term(),
                      endpoints :: term(),
                      started :: term()}.

Creates a service record for use with serve/2.

service_reply(ReplyKey, Payload)

-spec service_reply(ReplyKey ::
                        #nats_req{conn :: conn(),
                                  svc :: binary(),
                                  id :: binary(),
                                  reply_to :: undefined | binary()},
                    Payload :: iodata()) ->
                       ok.

Sends a reply to a service request.

service_reply(ReplyKey, Header, Payload)

-spec service_reply(ReplyKey ::
                        #nats_req{conn :: conn(),
                                  svc :: binary(),
                                  id :: binary(),
                                  reply_to :: undefined | binary()},
                    Header :: binary(),
                    Payload :: iodata()) ->
                       ok.

Sends a reply with headers to a service request.

sockname(Server)

-spec sockname(Server :: conn()) -> {ok, map()} | {error, timeout | closed}.

Retrieves the local socket address of the connection.

sub(Server, Subject)

-spec sub(Server :: conn(), Subject :: iodata()) -> {ok, sid()} | {error, timeout | not_ready}.

Subscribes to the specified subject with default options.

sub(Server, Subject, Opts)

-spec sub(Server :: conn(), Subject :: iodata(), Opts :: map()) ->
             {ok, sid()} | {error, timeout | not_ready}.

Subscribes to the specified subject with the given options.

unsub(Server, SRef)

-spec unsub(Server :: conn(), SRef :: sid()) -> ok | {error, timeout | not_ready | invalid_session_ref}.

Unsubscribes from the specified subscription reference.

unsub(Server, SRef, Opts)

-spec unsub(Server :: conn(), SRef :: sid(), Opts :: map()) ->
               ok | {error, timeout | not_ready | invalid_session_ref}.

Unsubscribes from the specified subscription reference with options (e.g., max messages).