Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: example for NATS cluster #2591

Merged
merged 2 commits into from
Jun 20, 2024
Merged

docs: example for NATS cluster #2591

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
92bd0df
chore: add cluster example
mdelapenya Jun 18, 2024
4883f19
docs: include missing methods and options for NATS
mdelapenya Jun 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions docs/modules/nats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,22 +44,54 @@ for NATS. E.g. `testcontainers.WithImage("nats:2.9")`.

#### Set username and password

- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

If you need to set different credentials, you can use `WithUsername` and `WithPassword`
options. By default, the username, the password are not set. To establish the connection with the NATS container:

<!--codeinclude-->
[Connect using the credentials](../../modules/nats/examples_test.go) inside_block:natsConnect
<!--/codeinclude-->

#### Cmd Arguments

- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

It's possible to pass extra arguments to the NATS container using the `testcontainers.WithArgument` option. E.g. `nats.WithArgument("cluster_name", "c1")`.
These arguments are passed to the NATS server when it starts, as part of the command line arguments of the entrypoint.

!!! note
Arguments do not need to be prefixed with `--`: the NATS container will add them automatically.

<!--codeinclude-->
[Passing arguments](../../modules/nats/examples_test.go) inside_block:withArguments
<!--/codeinclude-->

### Container Methods

The NATS container exposes the following methods:

#### ConnectionString

- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

This method returns the connection string to connect to the NATS container, using the default `4222` port.
It's possible to pass extra parameters to the connection string, in a variadic way.

<!--codeinclude-->
[Get connection string](../../modules/nats/nats_test.go) inside_block:connectionString
<!--/codeinclude-->

#### MustConnectionString

- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

Exactly like `ConnectionString`, but it panics if an error occurs, returning just a string.

## Examples

### NATS Cluster

<!--codeinclude-->
[NATS Cluster](../../modules/nats/examples_test.go) inside_block:cluster
<!--/codeinclude-->
155 changes: 155 additions & 0 deletions modules/nats/examples_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,13 @@ import (
"context"
"fmt"
"log"
"time"

natsgo "github.com/nats-io/nats.go"

"github.com/testcontainers/testcontainers-go"
"github.com/testcontainers/testcontainers-go/modules/nats"
"github.com/testcontainers/testcontainers-go/network"
)

func ExampleRunContainer() {
Expand Down Expand Up @@ -74,3 +76,156 @@ func ExampleRunContainer_connectWithCredentials() {
// Output:
// true
}

func ExampleRunContainer_cluster() {
ctx := context.Background()

nwr, err := network.New(ctx)
if err != nil {
log.Fatalf("failed to create network: %s", err)
}

// withArguments {
natsContainer1, err := nats.RunContainer(ctx,
network.WithNetwork([]string{"nats1"}, nwr),
nats.WithArgument("name", "nats1"),
nats.WithArgument("cluster_name", "c1"),
nats.WithArgument("cluster", "nats://nats1:6222"),
nats.WithArgument("routes", "nats://nats1:6222,nats://nats2:6222,nats://nats3:6222"),
nats.WithArgument("http_port", "8222"),
)
// }
if err != nil {
log.Fatalf("failed to start container: %s", err)
}
// Clean up the container
defer func() {
if err := natsContainer1.Terminate(ctx); err != nil {
log.Fatalf("failed to terminate container: %s", err)
}
}()

natsContainer2, err := nats.RunContainer(ctx,
network.WithNetwork([]string{"nats2"}, nwr),
nats.WithArgument("name", "nats2"),
nats.WithArgument("cluster_name", "c1"),
nats.WithArgument("cluster", "nats://nats2:6222"),
nats.WithArgument("routes", "nats://nats1:6222,nats://nats2:6222,nats://nats3:6222"),
nats.WithArgument("http_port", "8222"),
)
if err != nil {
log.Fatalf("failed to start container: %s", err) // nolint:gocritic
}
// Clean up the container
defer func() {
if err := natsContainer2.Terminate(ctx); err != nil {
log.Fatalf("failed to terminate container: %s", err)
}
}()

natsContainer3, err := nats.RunContainer(ctx,
network.WithNetwork([]string{"nats3"}, nwr),
nats.WithArgument("name", "nats3"),
nats.WithArgument("cluster_name", "c1"),
nats.WithArgument("cluster", "nats://nats3:6222"),
nats.WithArgument("routes", "nats://nats1:6222,nats://nats2:6222,nats://nats3:6222"),
nats.WithArgument("http_port", "8222"),
)
if err != nil {
log.Fatalf("failed to start container: %s", err) // nolint:gocritic
}
defer func() {
if err := natsContainer3.Terminate(ctx); err != nil {
log.Fatalf("failed to terminate container: %s", err)
}
}()

// cluster URL
servers := natsContainer1.MustConnectionString(ctx) + "," + natsContainer2.MustConnectionString(ctx) + "," + natsContainer3.MustConnectionString(ctx)

nc, err := natsgo.Connect(servers, natsgo.MaxReconnects(5), natsgo.ReconnectWait(2*time.Second))
if err != nil {
log.Fatalf("connecting to nats container failed:\n\t%v\n", err) // nolint:gocritic
}

{
// Simple Publisher
err = nc.Publish("foo", []byte("Hello World"))
if err != nil {
log.Fatalf("failed to publish message: %s", err) // nolint:gocritic
}
}

{
// Channel subscriber
ch := make(chan *natsgo.Msg, 64)
sub, err := nc.ChanSubscribe("channel", ch)
if err != nil {
log.Fatalf("failed to subscribe to message: %s", err) // nolint:gocritic
}

// Request
err = nc.Publish("channel", []byte("Hello NATS Cluster!"))
if err != nil {
log.Fatalf("failed to publish message: %s", err) // nolint:gocritic
}

msg := <-ch
fmt.Println(string(msg.Data))

err = sub.Unsubscribe()
if err != nil {
log.Fatalf("failed to unsubscribe: %s", err) // nolint:gocritic
}

err = sub.Drain()
if err != nil {
log.Fatalf("failed to drain: %s", err) // nolint:gocritic
}
}

{
// Responding to a request message
sub, err := nc.Subscribe("request", func(m *natsgo.Msg) {
err1 := m.Respond([]byte("answer is 42"))
if err1 != nil {
log.Fatalf("failed to respond to message: %s", err1) // nolint:gocritic
}
})
if err != nil {
log.Fatalf("failed to subscribe to message: %s", err) // nolint:gocritic
}

// Request
msg, err := nc.Request("request", []byte("what is the answer?"), 1*time.Second)
if err != nil {
log.Fatalf("failed to send request: %s", err) // nolint:gocritic
}

fmt.Println(string(msg.Data))

err = sub.Unsubscribe()
if err != nil {
log.Fatalf("failed to unsubscribe: %s", err) // nolint:gocritic
}

err = sub.Drain()
if err != nil {
log.Fatalf("failed to drain: %s", err) // nolint:gocritic
}
}

// Drain connection (Preferred for responders)
// Close() not needed if this is called.
err = nc.Drain()
if err != nil {
log.Fatalf("failed to drain connection: %s", err) // nolint:gocritic
}

// Close connection
nc.Close()

// Output:
// Hello NATS Cluster!
// answer is 42
}