Pillow

Remove the boilerplate in your embedded NATS projects, and deploy to cloud platforms with added functionality!

Warning

The API is unstable and subject to change until v1.0.0 is reached.

Getting Started

For simply embedding in a Go program:

go get github.com/Nintron27/pillow

then follow the embedded example.

For more examples:

• Reference the examples folder for examples of using pillow.
• This project was started and is being maintained to be used in the Stelo Finance project, so check that out for a real project example.

Features

• Removes boilerplate when using NATS embedded in Go, and implements sane defaults.
• Platform Adapters that automatically configure clustering, superclustering, and leaf nodes.
• Your needed feature here? Leave a feature request issue!

Platform Adapters Overview

The goal of Platform Adapters is to automatically configure your embedded nats server for certain network topologies when deployed on cloud platforms.

For example, the FlyioClustering Platform Adapter, enabled as such:

ns, err := pillow.Run(
  pillow.WithPlatformAdapter(context.TODO(), os.Getenv("ENV") == "prod", &pillow.FlyioClustering{
    ClusterName: "pillow-cluster", // Required, supply whatever value floats your boat
  }),
)

will use Flyio's Machine Runtime Environment and .internal DNS to configure your embedded server to:

1. Cluster with other machines in the same process group in the same region.
2. Form a supercluster with any other regions your process group may be deployed to.
3. Uniquely name your servers and append -<REGION> to your clusters' names.

Flyio

Currently there are only Platform Adapters for Flyio, and the two existing Adapters are:

• FlyioClustering: Auto clustering in region, supercluster regions together. (diagram)
• FlyioHubAndSpoke: Auto cluster primary region, and leaf node other regions' machines to your hub. (diagram)

Quirks w/ Platform Adapters

• You should supply pillow.WithPlatformAdapter last in your pillow.Run() call as it will override certain nats server options for platform specific reasons, such as overridding the server name so they are unique on every machine.
• FlyioClustering: Removing a region will cause any remaining machines will infinitely try to reconnect to the removed region, until they are restarted. This is probably fine, as it's just some network calls, but it is something to be aware of.
• FlyioClustering: When JetStream is enabled all your regions must have >= 3 nodes, as JetStream clustering requires this for a quorum.

Caution

Take great caution when switching adapters (such as HubAndSpoke to Clustering) as the cluster names and JS domains will change. Also caution with scaling down JS regions, as removing a node that contains a stream or kv bucket can cause an outage. You should evict them as a peer before removing the machine.

Forced Opinions

• NoSigs is forced to true for the nats-server configuration, as it generally doesn't align with embedding NATS in Go, but also causes problems with the Shutdown function due to nats-io/nats-server#6358.

Credit to @whaaaley for project name and icon, and @delaneyj for the inspiration.