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

proof reading commits

Browse Source
This commit is contained in:
ainsley
2019-05-30 12:38:58 -05:00
parent d35e3cb277
commit 602700010d
35 changed files with 100 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
developer/README.md
View File

@@ -1,6 +1,6 @@
# 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.
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 godoc, and the Java library has javadoc.
| Library | Doc Link |
| ------------- | ------------- |

2
developer/concepts/intro.md
View File

@@ -19,4 +19,4 @@ graph nats {
}
</code></div>
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.
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](/docs/nats_streaming/intro.md), or build the additional reliability into your client(s) yourself.

2
developer/connecting/cluster.md
View File

@@ -7,7 +7,7 @@ When connecting to a cluster, there are a few things to think about.
* The reconnect algorithm (discussed later)
* Server provided URLs
When a client library first tries to connect it will use the list of URLS provided to the connection options or function. These URLS are checked, usually in order, and the first successful connection is used.
When a client library first tries to connect it will use the list of URLs provided to the connection options or function. These URLs are checked, usually in order, and the first successful connection is used.
After a client connects to the server, the server may provide a list of URLs for additional known servers. This allows a client to connect to one server and still have other servers available during reconnect.

2
developer/receiving/drain.md
View File

@@ -1,6 +1,6 @@
# Draining Connections and Subscriptions
A new feature being added across the NATS client libraries is the ability to drain connections or subscriptions. Closing a connection, or unsubscribing from a subscription are generally considered immediate requests. When you close or unsubscribe the library will halt messages in any pending queue or cache for subscribers. When you drain a subscription or connection, it will process any cached/pending messages before closing.
A feature recently added across the NATS client libraries is the ability to drain connections or subscriptions. Closing a connection, or unsubscribing from a subscription are generally considered immediate requests. When you close or unsubscribe the library will halt messages in any pending queue or cache for subscribers. When you drain a subscription or connection, it will process any cached/pending messages before closing.
Drain provides clients that use queue subscriptions with a way to bring down applications without losing any messages. A client can bring up a new queue member, drain and shut down the old queue member, all without losing messages sent to the old client. Without drain, there is the possibility of lost messages due to queue timing.

2
developer/reconnect/intro.md
View File

@@ -6,4 +6,4 @@ In general, the client will try to connect to all of the servers it knows about,
The list of servers used during reconnect is library dependent, but generally is constructed from the list of servers passed to the connect function/options and the list of servers provided by the most recent connected server.
One, sometimes important, detail is that the server URLS provided to clients by servers will use addresses, while the URLS provided to the connect function will usually be host names. As a result, it is possible, on reconnect, for the same server to be tried multiple times without the client knowing about the match.
One, sometimes important, detail is that the server URLs provided to clients by servers will use addresses, while the URLs provided to the connect function will usually be host names. As a result, it is possible, on reconnect, for the same server to be tried multiple times without the client knowing about the match.

2
developer/security/nkey.md
View File

@@ -1,6 +1,6 @@
# 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.
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](https://ed25519.cr.yp.to/) 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.

2
developer/security/tls.md
View File

@@ -1,6 +1,6 @@
# Encrypting Connections with TLS
While authentication limits which clients can connect, TLS can be used to check the server’s identity and the client’s identity and will encrypt the traffic between the two. The most secure version of TLS with NATS is to use verified client certificates. In this mode, the client can check that it trusts the certificate sent by `nats-server` but the server will also check that it trusts the certificate sent by the client. From an applications perspective connecting to a server that does not verify client certificates may appear identical. Under the covers, disabling TLS verification removes the server side check on the client’s certificate. When started in TLS mode, `nats-server` will require all clients to connect with TLS. Moreover, if configured to connect with TLS, client libraries will fail to connect to a server without TLS.
While authentication limits which clients can connect, TLS can be used to check the server’s identity and the client’s identity and will encrypt the traffic between the two. The most secure version of TLS with NATS is to use verified client certificates. In this mode, the client can check that it trusts the certificate sent by `nats-server` but the server will also check that it trusts the certificate sent by the client. From an application's perspective connecting to a server that does not verify client certificates may appear identical. Under the covers, disabling TLS verification removes the server side check on the client’s certificate. When started in TLS mode, `nats-server` will require all clients to connect with TLS. Moreover, if configured to connect with TLS, client libraries will fail to connect to a server without TLS.
The [Java examples repository](https://github.com/nats-io/java-nats-examples/tree/master/src/main/resources) contains certificates for starting the server in TLS mode.

2
developer/security/token.md
View File

@@ -6,7 +6,7 @@ Tokens are basically random strings, much like a password, and can provide a sim
For this example, start the server using:
```sh
> gnatsd --auth mytoken
> nats-server --auth mytoken
```
The code uses localhost:4222 so that you can start the server on your machine to try them out.

50
developer/tutorials/pubsub.md
View File

@@ -15,7 +15,7 @@ digraph nats_pub_sub {
pub1 sub1 non_active
}
nats-server [shape="box", label="NATS", width=8];
gnatsd [shape="box", label="NATS", width=8];
sub2 [shape="box", label="SUB\ncom.msg.one"];
sub3 [shape="box", label="SUB\ncom.msg.two"];
@@ -26,13 +26,13 @@ digraph nats_pub_sub {
sub2 sub3 sub4
}
pub1 -> nats-server [penwidth=2];
nats-server -> sub1 [penwidth=2];
nats-server -> non_active [style=dashed color=red arrowhead="none"];
pub1 -> gnatsd [penwidth=2];
gnatsd -> sub1 [penwidth=2];
gnatsd -> non_active [style=dashed color=red arrowhead="none"];
nats-server -> sub2 [penwidth=2];
nats-server -> sub3 [style=dashed color=red arrowhead="none"];
nats-server -> sub4 [penwidth=2];
gnatsd -> sub2 [penwidth=2];
gnatsd -> sub3 [style=dashed color=red arrowhead="none"];
gnatsd -> sub4 [penwidth=2];
}
</code></div>
@@ -40,7 +40,7 @@ digraph nats_pub_sub {
Go and the NATS server should be installed.
## 1. Start the NATS server
### 1. Start the NATS server
```sh
% nats-server
@@ -56,17 +56,17 @@ When the server starts successfully, you will see the following messages:
The NATS server listens for client connections on TCP Port 4222.
## 2. Start a shell or command prompt session
### 2. Start a shell or command prompt session
You will use this session to run an example NATS client subscriber program.
## 3. CD to the Go client examples directory
### 3. CD to the Go client examples directory
```sh
% cd $GOPATH/src/github.com/nats-io/nats/examples
```
## 4. Run the client subscriber program
### 4. Run the client subscriber program
```sh
% go run nats-sub.go <subject>
@@ -82,7 +82,7 @@ For example:
You should see the message: *Listening on [msg.test]*
## 5. Start another shell or command prompt session
### 5. Start another shell or command prompt session
You will use this session to run a NATS publisher client.
@@ -92,7 +92,7 @@ You will use this session to run a NATS publisher client.
% cd $GOPATH/src/github.com/nats-io/nats/examples
```
## 7. Publish a NATS message
### 7. Publish a NATS message
```sh
% go run nats-pub.go <subject> <message>
@@ -112,7 +112,7 @@ or
% go run nats-pub.go msg.test "NATS MESSAGE"
```
## 8. Verify message publication and receipt
### 8. Verify message publication and receipt
You should see that the publisher sends the message: *Published [msg.test] : 'NATS MESSAGE'*
@@ -120,7 +120,7 @@ And that the subscriber receives the message: *[#1] Received on [msg.test]: 'NAT
Note that if the receiver does not get the message, check that you are using the same subject name for the publisher and the subscriber.
## 9. Publish another message
### 9. Publish another message
```sh
% go run nats-pub.go msg.test "NATS MESSAGE 2"
@@ -128,23 +128,23 @@ Note that if the receiver does not get the message, check that you are using the
You should see that the subscriber receive message 2. Note that the message count is incremented each time your subscribing client receives a message on that subject:
## 10. Start another shell or command prompt session
### 10. Start another shell or command prompt session
You will use this session to run a second NATS subscriber.
## 11. CD to the examples directory
### 11. CD to the examples directory
```sh
% cd $GOPATH/src/github.com/nats-io/nats/examples
```
## 12. Subscribe to the message
### 12. Subscribe to the message
```sh
% go run nats-sub.go msg.test
```
## 13. Publish another message using the publisher client
### 13. Publish another message using the publisher client
```sh
% go run nats-pub.go msg.test "NATS MESSAGE 3"
@@ -152,17 +152,17 @@ You will use this session to run a second NATS subscriber.
Verify that both subscribing clients receive the message.
## 14. Start another shell or command prompt session
### 14. Start another shell or command prompt session
You will use this session to run a third NATS subscriber.
## 15. CD to the examples directory
### 15. CD to the examples directory
```sh
% cd $GOPATH/src/github.com/nats-io/nats/examples
```
## 16. Subscribe to a different message
### 16. Subscribe to a different message
```sh
% go run nats-sub.go msg.test.new
@@ -170,9 +170,9 @@ You will use this session to run a third NATS subscriber.
All the but last subscriber receives the message. Why? Because that subscriber is not listening on the message subject used by the publisher.
## 17. Update the last subscriber to use a wildcard
### 17. Update the last subscriber to use a wildcard
NATS supports the use of wildcard characters for message subscribers. (You cannot publish a message using a wildcard subject.)
NATS supports the use of wildcard characters for message subscribers. You cannot publish a message using a wildcard subject.
Change the last subscriber the listen on msg.* and run it:
@@ -180,6 +180,6 @@ Change the last subscriber the listen on msg.* and run it:
% go run nats-sub.go msg.*
```
## 18. Publish another message
### 18. Publish another message
This time, all three subscribing clients should receive the message.

18
developer/tutorials/queues.md
View File

@@ -6,13 +6,13 @@ NATS supports a form of load balancing using queue groups. Subscribers register
Go and the NATS server should be installed.
## 1. Start the NATS server
### 1. Start the NATS server
```sh
nats-server
```
## 2. Clone the repositories for each client examples
### 2. Clone the repositories for each client examples
```sh
go get github.com/nats-io/go-nats
@@ -20,14 +20,14 @@ git clone https://github.com/nats-io/node-nats.git
git clone https://github.com/nats-io/ruby-nats.git
```
## 3. Run the Go client subscriber with queue group name
### 3. Run the Go client subscriber with queue group name
```sh
cd $GOPATH/src/github.com/nats-io/go-nats/examples
go run nats-qsub.go foo my-queue
```
## 4. Install and run the Node client subscriber with queue group name
### 4. Install and run the Node client subscriber with queue group name
```sh
npm install nats
@@ -35,34 +35,34 @@ cd node-nats/examples
node node-sub foo my-queue
```
## 5. Install and run the Ruby client subscriber with queue group name
### 5. Install and run the Ruby client subscriber with queue group name
```sh
gem install nats
nats-queue foo my-queue &
```
**6. Run another Go client subscriber *without* the queue group.
### 6. Run another Go client subscriber *without* the queue group.
```sh
cd $GOPATH/src/github.com/nats-io/go-nats/examples
go run nats-sub.go foo
```
## 7. Publish a NATS message using the Go client
### 7. Publish a NATS message using the Go client
```sh
cd $GOPATH/src/github.com/nats-io/go-nats/examples
go run nats-pub.go foo "Hello NATS!"
```
## 8. Verify message publication and receipt
### 8. Verify message publication and receipt
You should see that the publisher sends the message: *Published [foo] : 'Hello NATS!'*
You should see that only one of the my-queue group subscribers receives the message. In addition, the Go client subscriber not in the my-queue group should also receive the message.
## 9. Publish another message
### 9. Publish another message
```sh
go run nats-pub.go foo "Hello NATS Again!"

10
developer/tutorials/reqreply.md
View File

@@ -6,23 +6,23 @@ NATS supports request/reply messaging. In this tutorial you explore how to excha
Go and the NATS server should be installed.
## 1. Start the NATS server
### 1. Start the NATS server
```sh
% nats-server
```
## 2. Start two terminal sessions
### 2. Start two terminal sessions
You will use these sessions to run the NATS request and reply clients.
## 3. Change to the examples directory
### 3. Change to the examples directory
```sh
% cd $GOPATH/src/github.com/nats-io/nats/examples
```
## 4. In one terminal, run the reply client listener
### 4. In one terminal, run the reply client listener
```sh
% go run nats-rply.go foo "this is my response"
@@ -30,7 +30,7 @@ You will use these sessions to run the NATS request and reply clients.
You should see the message `Receiver is listening`, and that the NATS receiver client is listening on the "help.please" subject. The reply client acts as a receiver, listening for message requests. In NATS, the receiver is a subscriber.
## 5. In the other terminal, run the request client
### 5. In the other terminal, run the request client
```sh
% go run nats-req.go foo "request payload"