taigrr/nats.docs
1
0
Fork 0
mirror of https://github.com/taigrr/nats.docs synced 2025-01-18 04:03:23 -08:00
Code Issues Projects Releases Wiki Activity

Merge branch 'master' of github.com:nats-io/docs

Browse Source
This commit is contained in:
Alberto Ricart 2019-05-16 17:50:38 -05:00
commit e832940daf
13 changed files with 227 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
SUMMARY.md
View File

@ -54,11 +54,15 @@
## Developing With NATS
* [Intro](developer/README.md)
* [Concepts](developer/concepts/intro.md)
* [Subject-Based Messaging](developer/concepts/subjects.md)
* [Publish-Subscribe](developer/concepts/pubsub.md)
* [Request-Reply](developer/concepts/reqreply.md)
* [Using Queues to Share Work](developer/concepts/queue.md)
* [Subject-Based Messaging](developer/concepts/subjects.md)
* [Queue Groups](developer/concepts/queue.md)
* [Acknowledgements](developer/concepts/acks.md)
* [Sequence Numbers](developer/concepts/seq_num.md)
* [Connecting](developer/connecting/intro.md)
* [Connecting to the Default Server](developer/connecting/default_server.md)
@ -80,6 +84,8 @@
* [Securing Connections](developer/security/intro.md)
* [Authenticating with a User and Password](developer/security/userpass.md)
* [Authenticating with a Token](developer/security/token.md)
* [Authenticating with an NKey](developer/security/nkey.md)
* [Authenticating with a Credentials File](developer/security/creds.md)
* [Encrypting Connections with TLS](developer/security/tls.md)
* [Receiving Messages](developer/receiving/intro.md)

41
_examples/connect_creds.html Normal file
View File

@ -0,0 +1,41 @@
<div class="tab-wrap">
<input type="radio" id="connect_creds_go" name="connect_creds" class="tab" checked>
<label for="connect_creds_go" class="api-lang" data-language="go">Go</label>
<input type="radio" id="connect_creds_java" name="connect_creds" class="tab">
<label for="connect_creds_java" class="api-lang" data-language="java">Java</label>
<div class="tab__content">
<pre id="connect_creds_go_content"><a class="toolbar-icons pull-right" target="_blank" href="https://github.com/nats-io/go-nats-examples/blob/master/api-examples/connect_creds/main.go#L10-19"><i class="mdi mdi-github-circle" title="View on GitHub"></i></a><a class="toolbar-icons pull-right"><i class="mdi mdi-content-copy js-copy" title="Copy to Clipboard"></i></a><span class="copy-msg pull-right"></span><code class="language-go">nc, err := nats.Connect(&#34;localhost&#34;, nats.UserCredentials(&#34;path_to_creds_file&#34;))
if err != nil {
log.Fatal(err)
}
defer nc.Close()
// Do something with the connection
</code></pre>
</div>
<div class="tab__content">
<pre id="connect_creds_java_content"><a class="toolbar-icons pull-right" target="_blank" href="https://github.com/nats-io/java-nats-examples/blob/master/src/main/java/io/nats/examples/ConnectCreds.java#L11-21"><i class="mdi mdi-github-circle" title="View on GitHub"></i></a><a class="toolbar-icons pull-right"><i class="mdi mdi-content-copy js-copy" title="Copy to Clipboard"></i></a><span class="copy-msg pull-right"></span><code class="language-java">Options options = new Options.Builder().
server(&#34;nats://localhost:4222&#34;).
authHandler(Nats.credentials(&#34;path_to_creds_file&#34;)).
build();
Connection nc = Nats.connect(options);
// Do something with the connection
nc.close();
</code></pre>
</div>
</div>

66
_examples/connect_nkey.html Normal file
View File

@ -0,0 +1,66 @@
<div class="tab-wrap">
<input type="radio" id="connect_nkey_go" name="connect_nkey" class="tab" checked>
<label for="connect_nkey_go" class="api-lang" data-language="go">Go</label>
<input type="radio" id="connect_nkey_java" name="connect_nkey" class="tab">
<label for="connect_nkey_java" class="api-lang" data-language="java">Java</label>
<div class="tab__content">
<pre id="connect_nkey_go_content"><a class="toolbar-icons pull-right" target="_blank" href="https://github.com/nats-io/go-nats-examples/blob/master/api-examples/connect_nkey/main.go#L10-23"><i class="mdi mdi-github-circle" title="View on GitHub"></i></a><a class="toolbar-icons pull-right"><i class="mdi mdi-content-copy js-copy" title="Copy to Clipboard"></i></a><span class="copy-msg pull-right"></span><code class="language-go">opt, err := nats.NkeyOptionFromSeed(&#34;seed.txt&#34;)
if err != nil {
log.Fatal(err)
}
nc, err := nats.Connect(&#34;localhost&#34;, opt)
if err != nil {
log.Fatal(err)
}
defer nc.Close()
// Do something with the connection
</code></pre>
</div>
<div class="tab__content">
<pre id="connect_nkey_java_content"><a class="toolbar-icons pull-right" target="_blank" href="https://github.com/nats-io/java-nats-examples/blob/master/src/main/java/io/nats/examples/ConnectNKey.java#L16-47"><i class="mdi mdi-github-circle" title="View on GitHub"></i></a><a class="toolbar-icons pull-right"><i class="mdi mdi-content-copy js-copy" title="Copy to Clipboard"></i></a><span class="copy-msg pull-right"></span><code class="language-java">NKey theNKey = NKey.createUser(null); // really should load from somewhere
Options options = new Options.Builder().
server(&#34;nats://localhost:4222&#34;).
authHandler(new AuthHandler(){
public char[] getID() {
try {
return theNKey.getPublicKey();
} catch (GeneralSecurityException|IOException|NullPointerException ex) {
return null;
}
}
public byte[] sign(byte[] nonce) {
try {
return theNKey.sign(nonce);
} catch (GeneralSecurityException|IOException|NullPointerException ex) {
return null;
}
}
public char[] getJWT() {
return null;
}
}).
build();
Connection nc = Nats.connect(options);
// Do something with the connection
nc.close();
</code></pre>
</div>
</div>

12
developer/README.md Normal file
View File

@ -0,0 +1,12 @@
# Developing with NATS
Developing with NATS is a combination of distributed application techniques, common NATS features and library specific syntax. As well as using this book for guidance, some of the libraries contain language-familiar formats of their API. For example, the go library has go doc, and the Java library has javadoc.
| Library | Doc Link |
| ------------- | ------------- |
| [nats.go](https://github.com/nats-io/nats.go) | [godoc](http://godoc.org/github.com/nats-io/nats.go) |
| [nats.java](https://github.com/nats-io/nats.java) | [javadoc](https://javadoc.io/doc/io.nats/jnats) |
| [nats.net](https://github.com/nats-io/nats.net) | [doxygen](http://nats-io.github.io/nats.net/) |
| [nats.rb](https://github.com/nats-io/nats.rb) | [yard](https://www.rubydoc.info/gems/nats) |
Not all libraries contain this separate doc, depending on the language community, but be sure to check out the client libraries README for more information.

31
developer/concepts/acks.md Normal file
View File

@ -0,0 +1,31 @@
# Acknowledgements
In a system with at-most-once semantics, there are times when messages are lost. If your application is doing request-reply then it can simply use timeouts to handle network and application failures. When you are using one-way messaging the easiest way to insure message delivery is to turn it into a request-reply with the concept of an acknowledgement message, or ACKS. In NATS an ACK can simply be an empty message, a message with no body.
<div class="graphviz"><code data-viz="dot">
digraph nats_request_reply {
rankdir=LR
subgraph {
publisher [shape=box, style="rounded", label="Publisher"];
}
subgraph {
subject [shape=circle, label="Subject"];
reply [shape=circle, label="Reply"];
{rank = same subject reply}
}
subgraph {
sub1[shape=box, style="rounded", label="Subscriber"];
}
publisher -> subject [label="msg1"];
publisher -> reply [style="invis", weight=2];
subject -> sub1 [label="msg1"];
sub1 -> reply [label="ack"];
reply -> publisher;
}
</code></div>
Because the ACK can be empty it can take up very little network bandwidth, but the idea of the ACK turns a simple fire-and-forget into a fire-and-know world where the sender can be sure that the message was received by the other side, or with [scatter-gather](reqreply.md), several other sides.

10
developer/concepts/intro.md
View File

@ -1,6 +1,8 @@
# NATS Messaging Concepts
NATS messaging involves the electronic exchange of data among computer applications and provides a layer between the application and the underlying physical network. Application data is encoded as a message and sent by a publisher. The message is received, decoded, and processed by one or more subscribers. A subscriber can process a NATS message synchronously or asynchronously, depending on the client library used.
NATS messaging involves the electronic exchange of data among computer applications and provides a layer between the application and the underlying physical network. Application data is encoded as a message and sent by a publisher. The message is received, decoded, and processed by one or more subscribers.
By providing a central, easily discovered broker, NATS makes it easy for programs to communicate across different environments, languages, and systems. All clients have to do is connect to the broker, subscribe or publish to a subject and process messages. With this simple design, NATS lets programs share common message-handling code, isolate resources and interdependencies, and scale by easily handling an increase in message volume.
<div class="graphviz"><code data-viz="dot">
graph nats {
@ -17,8 +19,4 @@ graph nats {
}
</code></div>
Asynchronous processing uses a callback message handler to process messages. When a message arrives, the registered callback handler receives control to process the message. The client or the consuming application is not blocked from performing other work while it is waiting for a message. Asynchronous processing lets you create multi-threaded dispatching designs.
Synchronous processing requires that application code explicitly call a method to process an incoming message. Typically the message request is a blocking call that suspends processing until a message becomes available and if no message is available, the period for which the message processing call blocks, would be set by the client. Synchronous processing is typically used by a server whose purpose is to wait for and process incoming request messages and to send replies to the requesting application.
NATS makes it easy for programs to communicate across different environments, languages, and systems because all a client has to do is parse the message. NATS lets programs share common message-handling code, isolate resources and interdependencies, and scale by easily handling an increase in message volume.
NATS core offers an **at most once** quality of service. If a subscriber is not listening on the subject (no subject match), or is not active when the message is sent, the message is not received. This is the same level of guarantee that TCP/IP provides. By default, NATS is a fire-and-forget messaging system. If you need higher levels of service, you can either use NATS Streaming, or build the additional reliability into your client(s) yourself.

8
developer/concepts/pubsub.md
View File

@ -1,10 +1,6 @@
# Publish Subscribe
# Publish-Subscribe and Fan-Out
NATS implements a publish subscribe message distribution model as a one-to-many communication. A publisher sends a message on a subject and any active subscriber listening on that subject receives the message. Subscribers can also register interest in wildcard subjects that work a bit like a regular expression (but only a bit). NATS and NATS Streaming combine to offer two qualities of service:
- **At Most Once Delivery (NATS w/TCP reliability)** - In the basic NATS platform, if a subscriber is not listening on the subject (no subject match), or is not active when the message is sent, the message is not received. NATS is a fire-and-forget messaging system. If you need higher levels of service, you can either use NATS Streaming, or build the additional reliability into your client(s) yourself.
- **At Least Once Delivery (NATS Streaming)** - Some applications require higher levels of service and more stringent delivery guarantees but at the potential cost of lower message throughput and higher end-to-end delivery latency. These applications rely on the underlying messaging transport to ensure that messages are delivered to subscribers irrespective of network outages or whether or not a subscriber is offline at a particular point in time.
NATS implements a publish-subscribe message distribution model for one-to-many communication. A publisher sends a message on a subject and any active subscriber listening on that subject receives the message. Subscribers can also register interest in wildcard subjects that work a bit like a regular expression (but only a bit). This one-to-many pattern is sometimes called fan-out.
<div class="graphviz"><code data-viz="dot">
digraph nats_pub_sub {

2
developer/concepts/queue.md
View File

@ -4,6 +4,8 @@ NATS provides a load balancing feature called queue subscriptions. Using queue s
To create a queue subscription, subscribers register a queue name. All subscribers with the same queue name form the queue group. As messages on the registered subject are published, one member of the group is chosen randomly to receive the message. Although queue groups have multiple subscribers, each message is consumed by only one.
One of the great features of NATS is that queue groups are defined by the subscribers, not on the server. Applications can create new queue groups without any server change.
Queue subscribers are ideal for auto scaling as you can add or remove them anytime, without any configuration changes or restarting the server or clients.
<div class="graphviz"><code data-viz="dot">

4
developer/concepts/reqreply.md
View File

@ -1,6 +1,6 @@
# Request Reply
# Request-Reply and Scatter-Gather
NATS supports two flavors of request reply messaging: point-to-point or one-to-many. Point-to-point involves the fastest or first to respond. In a one-to-many exchange, you can set a limit on the number of responses the requestor may receive or use a timeout to limit on the speed of the response.
NATS supports two flavors of request reply messaging: point-to-point or one-to-many. Point-to-point involves the fastest or first to respond. In a one-to-many exchange, you can set a limit on the number of responses the requestor may receive or use a timeout to limit on the speed of the response. One-to-many request reply is sometimes called *scatter gather*.
In a request-response exchange the publish request operation publishes a message with a reply subject expecting a response on that reply subject. Many libraries allow you to use a function that will automatically wait for a response with a timeout. You can also handle that waiting process yourself.

25
developer/concepts/seq_num.md Normal file
View File

@ -0,0 +1,25 @@
# Sequence Numbers
A common problem for one-to-many messages is that a message can get lost or dropped due to a network failure. A simple pattern for resolving this situation is to include a sequence id with the message. Receivers can check the sequence id to see if they miss anything.
<div class="graphviz"><code data-viz="dot">
digraph nats_pub_sub {
rankdir=LR
publisher [shape=box, style="rounded", label="Publisher"];
subject [shape=circle, label="Subject"];
sub [shape=box, style="rounded", label="Subscriber"];
publisher -> subject [label="updates.1"];
publisher -> subject [label="updates.2"];
publisher -> subject [label="updates.3"];
subject -> sub [label="updates.*"];
}
</code></div>
In order to really leverage sequence ids there are a few things to keep in mind:
* Each sender will have to use their own sequence
* If possible, receivers should be able to ask for missing messages by id
With NATS you can embed sequence ids in the message, or you can include them in the subject. For example, a sender can send messages to `updates.1`, `updates.2`, etc... and the subscribers can listen to `updates.*` and optionally parse the subject to determine the sequence id.

4
developer/concepts/subjects.md
View File

@ -73,3 +73,7 @@ digraph g {
subject -> sub3 [label="msg"];
}
</code></div>
### Monitoring and Wire Taps
Subject to your security configuration, wildcards can be used for monitoring by creating something sometimes called a *wire tap*. In the simplest case you can create a subscriber for `>`. This application will receive all messages, again subject to security settings, sent on your NATS cluster.

23
developer/security/creds.md Normal file
View File

@ -0,0 +1,23 @@
# Authenticating with User Credentials File
The 2.0 version of NATS server introduced the idea of JWT-based authentication. Clients interact with this new scheme using a user JWT and the private key from an NKey pair. To help make connecting with a JWT easier, the client libraries support the concept of a credentials file. This file contains both the private key and the JWT and can be generated with the `nsc` tool. The contents will look like the following and should be protected because it contains a private key. This creds file is unused and only for example purposes.
```ascii
-----BEGIN NATS USER JWT-----
eyJ0eXAiOiJqd3QiLCJhbGciOiJlZDI1NTE5In0.eyJqdGkiOiJUVlNNTEtTWkJBN01VWDNYQUxNUVQzTjRISUw1UkZGQU9YNUtaUFhEU0oyWlAzNkVMNVJBIiwiaWF0IjoxNTU4MDQ1NTYyLCJpc3MiOiJBQlZTQk0zVTQ1REdZRVVFQ0tYUVM3QkVOSFdHN0tGUVVEUlRFSEFKQVNPUlBWV0JaNEhPSUtDSCIsIm5hbWUiOiJvbWVnYSIsInN1YiI6IlVEWEIyVk1MWFBBU0FKN1pEVEtZTlE3UU9DRldTR0I0Rk9NWVFRMjVIUVdTQUY3WlFKRUJTUVNXIiwidHlwZSI6InVzZXIiLCJuYXRzIjp7InB1YiI6e30sInN1YiI6e319fQ.6TQ2ilCDb6m2ZDiJuj_D_OePGXFyN3Ap2DEm3ipcU5AhrWrNvneJryWrpgi_yuVWKo1UoD5s8bxlmwypWVGFAA
------END NATS USER JWT------
************************* IMPORTANT *************************
NKEY Seed printed below can be used to sign and prove identity.
NKEYs are sensitive and should be treated as secrets.
-----BEGIN USER NKEY SEED-----
SUAOY5JZ2WJKVR4UO2KJ2P3SW6FZFNWEOIMAXF4WZEUNVQXXUOKGM55CYE
------END USER NKEY SEED------
*************************************************************
```
Given a creds file, a client can authenticate as a specific user belonging to a specific account:
!INCLUDE "../../_examples/connect_creds.html"

7
developer/security/nkey.md Normal file
View File

@ -0,0 +1,7 @@
# Authenticating with an NKey
The 2.0 version of NATS server introduces a new challenge response authentication option. This challenge response is based on a wrapper we call NKeys which uses ED25519 signing. The server can use these keys in several ways for authentication. The simplest is for the server to be configured with a list of known public keys and for the clients to respond to the challenge by signing it with its private key. This challenge-response insures security by insuring that the client has the private key, but also protects the private key from the server which never has to actually see it.
Handling challenge response may require more than just a setting in the connection options, depending on the client library.
!INCLUDE "../../_examples/connect_nkey.html"