pillow

README

Pillow

A soft little wrapper for NATS ^-^

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

[!WARNING] The Pillow API is unstable until v1.0.0 and as such may be subject to change in future releases 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.

Features

• Removes boilerplate when using NATS embedded in Go, and implements sane defaults.
• Flyio Adapters
  • Clustering: Auto clustering in region, supercluster regions together.
  • HubAndSpoke: Auto cluster primary region, and leaf node other regions' machines to your hub.
• Your needed feature here? Leave a feature request issue!

Examples

• Reference the examples folder for examples of using nats-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.

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.

Quirks with Platform Adapters

• 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.
• Flyio (Clustering & HubAndSpoke): Scaling down a JetStream enabled region may cause the JS quorum to fail, or the meta leader to not be established. This renders JS unuseable, and will hopefully be fixed or addressed in a future release.

[!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 there seems to be a bug with quorums failing.

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

Documentation

Index

• Constants
• Variables
• type FlyioClustering
  • func (c *FlyioClustering) Configure(ctx context.Context) Option
• type FlyioHubAndSpoke
  • func (c *FlyioHubAndSpoke) Configure(ctx context.Context) Option
• type Option
  • func WithInProcessClient(enable bool) Option
  • func WithLogging(enable bool) Option
  • func WithNATSServerOptions(natsServerOpts *server.Options) Option
  • func WithPlatformAdapter(ctx context.Context, enable bool, platformCfgr PlatformConfigurator) Option
  • func WithTimeout(t time.Duration) Option
• type PlatformConfigurator
• type Server
  • func Run(opts ...Option) (*nats.Conn, *Server, error)
  • func (s *Server) Shutdown(ctx context.Context) error

Constants

const (
	ClusterPort  int = 4244
	GatewayPort  int = 7244
	LeafNodePort int = 7422
)

Variables

var Client *nats.Conn

Global variable of the nats client created from Run().

If you are starting multiple embedded NATS servers, it's recommended to use the client returned from Run() as this Client will just be from the last invocation of Run().

var ErrEnvVarNotFound = errors.New("Platform ENV not found")

A platform specific environment variable could not be found. This should only occur if you are trying to use a platform adapter like AdapterFlyio() while not actually deploying on Flyio.

If this error does occur when still deploying on the correct platform respective to your Adapter, this may be that the platform changed their environment implementation. If so, file an issue.

var ErrPlatformImplementationChanged = errors.New("Platform implementation changed")

Should only occur when a platform changes something in their implementation. Pillow makes assumeptions that platforms tooling will not change, but if it does this error is returned.

Types

type FlyioClustering

type FlyioClustering struct {
	// The name to be used for clustering. Appended will be `-<REGION>` where REGION is the
	// Flyio region this cluster is in.
	ClusterName string
}

FlyioClustering will cluster all intra-region machines, and super cluster regions together. Note, if JetStream is enabled ALL regions must have >= 3 machines.

func (*FlyioClustering) Configure

func (c *FlyioClustering) Configure(ctx context.Context) Option

type FlyioHubAndSpoke

type FlyioHubAndSpoke struct {
	// The name to be used for the primary region cluster.
	ClusterName string
}

FlyioHubAndSpoke will cluster all machines in your primary region, and then all other regions will have their machines individually connect to your primary region cluster as leaf nodes.

Additionally, the primary region cluster will have the JS domain of "hub" and the leaf nodes will have the structure of "leaf-<REGION>-<MACHINE_ID>"

func (*FlyioHubAndSpoke) Configure

func (c *FlyioHubAndSpoke) Configure(ctx context.Context) Option

type Option

type Option func(*options) error

func WithInProcessClient

func WithInProcessClient(enable bool) Option

If enabled the returned client from Run() (and global pillow.Client) will communicate in-process and not over the network layer

func WithLogging

func WithLogging(enable bool) Option

Enable NATS internal logging

func WithNATSServerOptions

func WithNATSServerOptions(natsServerOpts *server.Options) Option

Apply your own NATs Server Options. Note, this will override any existing options, so it's recommended to place first in the list of options in Run().

func WithPlatformAdapter

func WithPlatformAdapter(ctx context.Context, enable bool, platformCfgr PlatformConfigurator) Option

func WithTimeout

func WithTimeout(t time.Duration) Option

Duration to wait for embedded NATS to start. Defaults to 5 seconds if omitted

type PlatformConfigurator

type PlatformConfigurator interface {
	Configure(context.Context) Option
}

type Server

type Server struct {
	NATSServer *server.Server
	// contains filtered or unexported fields
}

func Run

func Run(opts ...Option) (*nats.Conn, *Server, error)

Applies all passed options and starts the NATS server, returning a client connection, a server struct, and error if there was a problem starting the server.

All configuration functions start with "With". Example WithLogging(true)

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error