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

GitBook: [master] 326 pages and 16 assets modified

Browse Source
This commit is contained in:
Ginger Collison
2019-10-04 17:48:52 +00:00
committed by gitbook-bot
parent 8b7ba5c3bb
commit fb0d5c8355
203 changed files with 4640 additions and 3107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
developing-with-nats/intro-6/README.md Normal file
View File

@@ -0,0 +1,9 @@
# Tutorials
Tutorials are provided to give guidance on commonly used aspects of NATS.
* [Explore NATS Publish/Subscribe](pubsub.md)
* [Explore NATS Request/Reply](reqreply.md)
* [Explore NATS Queueing](queues.md)
* [Advanced Connect and Custom Dialer in Go](custom_dialer.md)

128
developing-with-nats/intro-6/custom_dialer.md Normal file
View File

@@ -0,0 +1,128 @@
# Advanced Connect and Custom Dialer in Go
The Go NATS client features a [CustomDialer](https://godoc.org/github.com/nats-io/go-nats#CustomDialer) option which allows you to customize the connection logic against the NATS server without having to modify the internals of the client. For example, let's say that you want to make the client use the `context` package to use `DialContext` and be able to cancel connecting to NATS altogether with a deadline, you could then do define a Dialer implementation as follows:
```go
package main
import (
"context"
"log"
"net"
"time"
"github.com/nats-io/nats.go"
)
type customDialer struct {
ctx context.Context
nc *nats.Conn
connectTimeout time.Duration
connectTimeWait time.Duration
}
func (cd *customDialer) Dial(network, address string) (net.Conn, error) {
ctx, cancel := context.WithTimeout(cd.ctx, cd.connectTimeout)
defer cancel()
for {
log.Println("Attempting to connect to", address)
if ctx.Err() != nil {
return nil, ctx.Err()
}
select {
case <-cd.ctx.Done():
return nil, cd.ctx.Err()
default:
d := &net.Dialer{}
if conn, err := d.DialContext(ctx, network, address); err == nil {
log.Println("Connected to NATS successfully")
return conn, nil
} else {
time.Sleep(cd.connectTimeWait)
}
}
}
}
```
With the dialer implementation above, the NATS client will retry a number of times to connect to the NATS server until the context is no longer valid:
```go
func main() {
// Parent context cancels connecting/reconnecting altogether.
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
var err error
var nc *nats.Conn
cd := &customDialer{
ctx: ctx,
connectTimeout: 10 * time.Second,
connectTimeWait: 1 * time.Second,
}
opts := []nats.Option{
nats.SetCustomDialer(cd),
nats.ReconnectWait(2 * time.Second),
nats.ReconnectHandler(func(c *nats.Conn) {
log.Println("Reconnected to", c.ConnectedUrl())
}),
nats.DisconnectHandler(func(c *nats.Conn) {
log.Println("Disconnected from NATS")
}),
nats.ClosedHandler(func(c *nats.Conn) {
log.Println("NATS connection is closed.")
}),
nats.NoReconnect(),
}
go func() {
nc, err = nats.Connect("127.0.0.1:4222", opts...)
}()
WaitForEstablishedConnection:
for {
if err != nil {
log.Fatal(err)
}
// Wait for context to be canceled either by timeout
// or because of establishing a connection...
select {
case <-ctx.Done():
break WaitForEstablishedConnection
default:
}
if nc == nil || !nc.IsConnected() {
log.Println("Connection not ready")
time.Sleep(200 * time.Millisecond)
continue
}
break WaitForEstablishedConnection
}
if ctx.Err() != nil {
log.Fatal(ctx.Err())
}
for {
if nc.IsClosed() {
break
}
if err := nc.Publish("hello", []byte("world")); err != nil {
log.Println(err)
time.Sleep(1 * time.Second)
continue
}
log.Println("Published message")
time.Sleep(1 * time.Second)
}
// Disconnect and flush pending messages
if err := nc.Drain(); err != nil {
log.Println(err)
}
log.Println("Disconnected")
}
```

154
developing-with-nats/intro-6/pubsub.md Normal file
View File

@@ -0,0 +1,154 @@
# Explore NATS Pub/Sub
NATS is a publish subscribe messaging system. Subscribers listening on a subject receive messages on that subject. If the subscriber is not actively listening on the subject, the message is not received. Subscribers can use the wildcard tokens such as `*` and `>` to match a single token or to match the tail of a subject.
![](../../.gitbook/assets/pubsubtut.svg)
## Prerequisites
Go and the NATS server should be installed. Optionally you can use the demo server located at `nats://demo.nats.io`
### 1. Start the NATS server
```bash
% nats-server
```
When the server starts successfully, you will see the following messages:
```bash
[1] 2019/31/05 15:18:22.301550 [INF] Starting nats-server version 2.0.0
[1] 2019/31/05 15:18:22.301762 [INF] Listening for client connections on 0.0.0.0:4222
[1] 2019/31/05 15:18:22.301769 [INF] nats-server is ready
```
The NATS server listens for client connections on TCP Port 4222.
### 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
```bash
% cd $GOPATH/src/github.com/nats-io/nats.go/examples
```
### 4. Run the client subscriber program
```bash
% go run nats-sub/main.go <subject>
```
Where `<subject>` is a subject to listen on. A valid subject is a string that is unique in the system.
For example:
```bash
% go run nats-sub/main.go msg.test
```
You should see the message: _Listening on \[msg.test\]_
### 5. Start another shell or command prompt session
You will use this session to run a NATS publisher client.
## 6. CD to the examples directory
```bash
% cd $GOPATH/src/github.com/nats-io/nats.go/examples
```
### 7. Publish a NATS message
```bash
% go run nats-pub/main.go <subject> <message>
```
Where `<subject>` is the subject name and `<message>` is the text to publish.
For example:
```bash
% go run nats-pub/main.go msg.test hello
```
or
```bash
% go run nats-pub/main.go msg.test "NATS MESSAGE"
```
### 8. Verify message publication and receipt
You should see that the publisher sends the message: _Published \[msg.test\] : 'NATS MESSAGE'_
And that the subscriber receives the message: _\[\#1\] Received on \[msg.test\]: 'NATS MESSAGE'_
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
```bash
% go run nats-pub/main.go msg.test "NATS MESSAGE 2"
```
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
You will use this session to run a second NATS subscriber.
### 11. CD to the examples directory
```bash
% cd $GOPATH/src/github.com/nats-io/nats.go/examples
```
### 12. Subscribe to the message
```bash
% go run nats-sub/main.go msg.test
```
### 13. Publish another message using the publisher client
```bash
% go run nats-pub/main.go msg.test "NATS MESSAGE 3"
```
Verify that both subscribing clients receive the message.
### 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
```bash
% cd $GOPATH/src/github.com/nats-io/nats.go/examples
```
### 16. Subscribe to a different message
```bash
% go run nats-sub/main.go msg.test.new
```
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
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:
```bash
% go run nats-sub/main.go msg.*
```
### 18. Publish another message
This time, all three subscribing clients should receive the message.

72
developing-with-nats/intro-6/queues.md Normal file
View File

@@ -0,0 +1,72 @@
# Explore NATS Queueing
NATS supports a form of load balancing using queue groups. Subscribers register a queue group name. A single subscriber in the group is randomly selected to receive the message.
## Prerequisites
Go and the NATS server should be installed.
### 1. Start the NATS server
```bash
nats-server
```
### 2. Clone the repositories for each client examples
```bash
go get github.com/nats-io/nats.go
git clone https://github.com/nats-io/nats.js.git
git clone https://github.com/nats-io/nats.rb.git
```
### 3. Run the Go client subscriber with queue group name
```bash
cd $GOPATH/src/github.com/nats-io/nats.go/examples
go run nats-qsub/main.go foo my-queue
```
### 4. Install and run the Node client subscriber with queue group name
```bash
npm install nats
cd nats.js/examples
node node-sub --queue=my-queue foo
```
### 5. Install and run the Ruby client subscriber with queue group name
```bash
gem install nats
nats-queue foo my-queue &
```
### 6. Run another Go client subscriber _without_ the queue group.
```bash
cd $GOPATH/src/github.com/nats-io/nats.go/examples
go run nats-sub/main.go foo
```
### 7. Publish a NATS message using the Go client
```bash
cd $GOPATH/src/github.com/nats-io/nats.go/examples
go run nats-pub/main.go foo "Hello NATS!"
```
### 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
```bash
go run nats-pub/main.go foo "Hello NATS Again!"
```
You should see that a different queue group subscriber receives the message this time, chosen at random among the 3 queue group members.

42
developing-with-nats/intro-6/reqreply.md Normal file
View File

@@ -0,0 +1,42 @@
# Explore NATS Request/Reply
NATS supports request/reply messaging. In this tutorial you explore how to exchange point-to-point messages using NATS.
## Prerequisites
Go and the NATS server should be installed.
### 1. Start the NATS server
```bash
% nats-server
```
### 2. Start two terminal sessions
You will use these sessions to run the NATS request and reply clients.
### 3. Change to the examples directory
```bash
% cd $GOPATH/src/github.com/nats-io/nats.go/examples
```
### 4. In one terminal, run the reply client listener
```bash
% go run nats-rply/main.go foo "this is my response"
```
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
```bash
% go run nats-req/main.go foo "request payload"
```
The NATS requestor client makes a request by sending the message "some message" on the “help.please” subject.
The NATS receiver client receives the message, formulates the reply \("OK, I CAN HELP!!!\), and sends it to the inbox of the requester.