Embedding NATS Streaming Server

Embedding a NATS Streaming Server in your own code is easy. Simply import:

  1.   stand "github.com/nats-io/nats-streaming-server/server"

(Note: we chose stand here, but you don’t have to use that name)

Then if you want to use default options, it is as simple as doing:

  1.   s, err := stand.RunServer("mystreamingserver")

If you want a more advance configuration, then you need to pass options. For instance, let’s start the server with a file store instead of memory.

First import the stores package so we have access to the store type.

  1.   stores "github.com/nats-io/nats-streaming-server/stores"

Then get the default options and override some of them:

  1.   opts := stand.GetDefaultOptions()
  2.   opts.StoreType = stores.TypeFile
  3.   opts.FilestoreDir = "datastore"
  4.   s, err := stand.RunServerWithOpts(opts, nil)

However, since the NATS Streaming Server project vendors NATS Server that is uses as the communication layer with its clients and other servers in the cluster, there are some limitations.

If you were to import github.com/nats-io/nats-server/server, instantiate a NATS Options structure, configure it and pass it to the second argument of RunServerWithOpts, you would get a compiler error. For instance doing this does not work:

  1. import (
  2.   natsd "github.com/nats-io/nats-server/server"
  3.   stand "github.com/nats-io/nats-streaming-server/server"
  4.   stores "github.com/nats-io/nats-streaming-server/stores"
  5. )
  7. (...)
  9.   nopts := &natsd.Options{}
  10.   nopts.Port = 4223
  12.   s, err := stand.RunServerWithOpts(nil, nopts)

You would get:

  1. ./myapp.go:36:35: cannot use nopts (type *"myapp/vendor/github.com/nats-io/nats-server/server".Options) as type *"myapp/vendor/github.com/nats-io/nats-streaming-server/vendor/github.com/nats-io/gnatsd/server".Options in argument to "myapp/vendor/github.com/nats-io/nats-streaming-server/server".RunServerWithOpts

To workaround this issue, the NATS Streaming Server package provides a function NewNATSOptions() that is suitable for this approach:

  1.   nopts := stand.NewNATSOptions()
  2.   nopts.Port = 4223
  4.   s, err := stand.RunServerWithOpts(nil, nopts)

That will work.

But, if you want to do advanced NATS configuration that requires types or interfaces that belong to the NATS Server package, then this approach won’t work. In this case, you need to run the NATS Server independently and have the NATS Streaming Server connect to it.

  1.   // This configure the NATS Server using natsd package
  2.   nopts := &natsd.Options{}
  3.   nopts.HTTPPort = 8222
  4.   nopts.Port = 4223
  6.   // Setting a customer client authentication requires the NATS Server Authentication interface.
  7.   nopts.CustomClientAuthentication = &myCustomClientAuth{}
  9.   // Create the NATS Server
  10.   ns := natsd.New(nopts)
  12.   // Start it as a go routine
  13.   go ns.Start()
  15.   // Wait for it to be able to accept connections
  16.   if !ns.ReadyForConnections(10 * time.Second) {
  17.     panic("not able to start")
  18.   }
  20.   // Get NATS Streaming Server default options
  21.   opts := stand.GetDefaultOptions()
  23.   // Point to the NATS Server with host/port used above
  24.   opts.NATSServerURL = "nats://localhost:4223"
  26.   // Now we want to setup the monitoring port for NATS Streaming.
  27.   // We still need NATS Options to do so, so create NATS Options
  28.   // using the NewNATSOptions() from the streaming server package.
  29.   snopts := stand.NewNATSOptions()
  30.   snopts.HTTPPort = 8223
  32.   // Now run the server with the streaming and streaming/nats options.
  33.   s, err := stand.RunServerWithOpts(opts, snopts)
  34.   if err != nil {
  35.     panic(err)
  36.   }

The above process may seem involved, but only if you use very advanced NATS Server options.