{"id":16389634,"url":"https://github.com/yuce/teacup_nats","last_synced_at":"2026-03-10T12:31:32.756Z","repository":{"id":143659848,"uuid":"54239666","full_name":"yuce/teacup_nats","owner":"yuce","description":"Teacup based NATS client for Erlang","archived":false,"fork":false,"pushed_at":"2023-10-13T15:15:14.000Z","size":144,"stargazers_count":17,"open_issues_count":1,"forks_count":9,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-03-14T21:45:38.131Z","etag":null,"topics":["client","erlang","nats"],"latest_commit_sha":null,"homepage":"","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yuce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-03-19T00:40:20.000Z","updated_at":"2023-10-13T04:08:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"2914fdc8-c19e-4378-949c-d7bd91897b61","html_url":"https://github.com/yuce/teacup_nats","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuce%2Fteacup_nats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuce%2Fteacup_nats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuce%2Fteacup_nats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuce%2Fteacup_nats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yuce","download_url":"https://codeload.github.com/yuce/teacup_nats/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245056889,"owners_count":20553855,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","erlang","nats"],"created_at":"2024-10-11T04:33:51.160Z","updated_at":"2025-12-12T00:14:20.150Z","avatar_url":"https://github.com/yuce.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Teacup NATS\n\nA [Teacup](https://github.com/yuce/teacup.git) based Erlang client library for [NATS](http://nats.io/)\nhigh performance messaging platform.\n\n## NEWS\n\n* **2016-04-17**: Version 0.4.0:\n\n    * Renamed `tcnats` module to `nats`.\n    * Added `nats:is_ready/1` function to check whether a NATS connection\n    is ready (to pub, sub, unsub).\n    * Added initial tests.\n\n* **2016-04-16**: Version 0.3.7:\n\n    * Re-licenced the project under [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).    \n    * This version fixes performance problems introduced in version 0.3.3.\n\n* **2016-04-07**: Version 0.3.4:\n\n    * Rudimentary TLS/SSL support. Currently, this is auto-activated when the server\n    sends `tls_required =\u003e true` in an `INFO` message. \n\n* **2016-04-03**: Version 0.3.3:\n\n    * Using [teacup 0.3.3](https://github.com/yuce/teacup/tree/0.3.3),\n    which boosts the performance by 50%.\n    * Implemented connect retry / reconnect strategy.\n    * Implemented message buffering.\n    * Sub and Unsub messages are queued.\n\n* **2016-03-27**: You can check how the performance of **teacup_nats** compares to other NATS clients\n[here](https://github.com/yuce/nats-client-benchmarks).\n\n* **2016-03-19**: Initial release.\n\n## Getting Started\n\n**teacup_nats** requires Erlang/OTP 18.0+. It uses [rebar3](http://www.rebar3.org/)\nas the build tool and is available on [hex.pm](https://hex.pm/). Just include the following\nin your `rebar.config`:\n\n```erlang\n{deps, [teacup_nats]}.\n```\n\nIf you are upgrading from an earlier version, you need to:\n\n```\n$ rebar3 update \u0026\u0026 rebar3 upgrade\n```\n\n**teacup_nats** depends on the `teacup` app to be started. Include it in your `.app.src` file:\n\n```erlang\n...\n  {applications,\n   [kernel,\n    stdlib,\n    teacup\n   ]},\n...\n```\n\nOr, start it manually:\n\n```erlang\nok = application:start(teacup).\n```\n\n**rebar3** has a nice way of starting apps in the shell, you can try:\n\n```\n$ rebar3 shell --apps teacup\n```\n\n## Running the Tests\n\n```\n$ rebar3 ct\n```\n\n## TODO\n\n* Clustering\n\n## API\n\n### Aysnchronous Connection\n\nWhen using asycnhronous connections, you need to wait for a `{Conn, ready}`\nmessage before publishing messages, subcribing to/unsubscribing from subjects.\n\n* Connection functions:\n    * `nats:connect()`: Connect to the NATS server at address `127.0.0.1`, port `4222`,\n    * `nats:connect(Host :: binary(), Port :: integer())`: Connect to the NATS server\n    at `Host` and port `PORT`,\n    * `nats:connect(Host :: binary(), Port :: integer(), Opts :: map())`: Similar to\n    above, but also takes an `Opts` map. Currently usable keys:\n        * `verbose =\u003e true | false`: If `verbose == true`, NATS server\n        sends an acknowledgement message on `pub`, `sub`, `unsub` operations and\n        `connect` operation becomes synchronous.\n        * `user =\u003e User :: binary()`,\n        * `pass =\u003e Password :: binary()`,\n        * `buffer_size =\u003e MessageBufferSize :: non_neg_integer()`: The number of publish messages\n        to buffer before quitting. The default is 0. Setting `MesssageBufferSize` to\n        `infinity` enables unlimited buffering.\n        * `reconnect =\u003e {Interval :: non_neg_integer(), MaxRetry :: non_neg_integer()}`: Specifies\n        reconnect strategy. `Interval` is the time in milliseconds between retrials, and `MaxRetry` is\n        the number of retrials before quitting. You can set `MaxRetry` to `infinity` to try reconnecting\n        forever. The default is `{undefined, 0}`, \"don't try to reconnect\".\n* Publish functions:\n    * `nats:pub(Conn :: teacup_ref(), Subject :: binary())`: Publish message with only\n    the subject,\n    * `nats:pub(Conn :: teacup_ref(), Subject :: binary()), Opts :: map()`: Publish message\n    the subject with `Options`. Valid options:\n        * `payload =\u003e Payload :: binary()`,\n        * `reply_to =\u003e Subject :: binary()`\n* Subscribe functions:\n    * `nats:sub(Conn :: teacup_ref(), Subject :: binary())`: Subscribe to the `Subject`,\n    * `nats:sub(Conn :: teacup_ref(), Subject :: binary(), Opts :: map())`: Subscribe to the `Subject`, with\n    `Options`. Valid options:\n        * `queue_group =\u003e QGroup :: binary()`\n* Unsubscribe functions:\n    * `nats:unsub(Conn :: teacup_ref(), Subject :: binary())`: Unsubscribe from `Subject`,\n    * `nats:unsub(Conn :: teacup_ref(), Subject :: binary(), Opts :: map())`: Unsubscribe from `Subject`, with\n    `Options`. Valid options:\n        * `max_messages =\u003e MaxMessages :: integer()`: Automatically unsubscribe after receiving `MaxMessages`.\n\n#### Sample\n\n```erlang\nmain() -\u003e\n    % Connect to the NATS server\n    {ok, Conn} = nats:connect(\u003c\u003c\"demo.nats.io\"\u003e\u003e, 4222, #{buffer_size =\u003e 10}),\n    % We set the buffer_size, so messages will be collected on the client side\n    %   until the connection is OK to use \n    % Publish some message\n    nats:pub(Conn, \u003c\u003c\"teacup.control\"\u003e\u003e, #{payload =\u003e \u003c\u003c\"start\"\u003e\u003e}),\n    % subscribe to some subject\n    nats:sub(Conn, \u003c\u003c\"foo.*\"\u003e\u003e),\n    loop(Conn).\n\nloop(Conn) -\u003e\n    receive\n        {Conn, {msg, Subject, _ReplyTo, Payload}} -\u003e\n            % Do something with the received message\n            io:format(\"~p: ~p~n\", [Subject, Payload]),\n            % Wait for/retrieve the next message\n            loop(Conn)\n    end.\n```\n\n### Synchronous Connection\n\nIn order to activate the synchronous mode, just pass `#{verbose =\u003e true` to `nats:connect`.\n\nConnect, publish, subscribe and unsubscribe operations block and return either `ok` on\nsuccess or `{error, Reason :: term()}` on failure.\n\n#### Sample\n\n```erlang\nmain() -\u003e\n    % Connect to the NATS server\n    {ok, Conn} = nats:connect(\u003c\u003c\"demo.nats.io\"\u003e\u003e, 4222, #{verbose =\u003e true}),\n    % The connection is OK to use\n    % Publish some message\n    ok = nats:pub(Conn, \u003c\u003c\"teacup.control\"\u003e\u003e, #{payload =\u003e \u003c\u003c\"start\"\u003e\u003e}),\n    % subscribe to some subject\n    ok = nats:sub(Conn, \u003c\u003c\"foo.*\"\u003e\u003e),\n    loop(Conn).\n\nloop(Conn) -\u003e\n    receive\n        {Conn, {msg, Subject, _ReplyTo, Payload}} -\u003e\n            % Do something with the received message\n            io:format(\"~p: ~p~n\", [Subject, Payload]),\n            loop(Conn)\n    end.\n\n```\n\n## License\n\n```\nCopyright 2016 Yuce Tekol \u003cyucetekol@gmail.com\u003e\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuce%2Fteacup_nats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuce%2Fteacup_nats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuce%2Fteacup_nats/lists"}