supervisor

Documentation

Overview

Package supervisor provides the development kit for running Blacksmith applications in a distributed environment. The supervisor is used to make sure resources are accessed by a single instance of the gateway and the scheduler to avoid collision when listening for events, executing jobs, or running migrations.

Note: The supervisor is part of Blacksmith Enterprise Edition and is not leveraged when using Blacksmith Standard Edition.

Index

• Variables
• type Lock
• type Node
• type Options
• type Registry
• type Service
• type Supervisor
• type Toolkit

Variables

var AvailableAdapters = map[string]bool{
	"consul": true,
}

AvailableAdapters is a list of available supervisors adapters.

var Defaults = &Options{
	Context: context.Background(),
	Join: &Node{
		Tags: []string{"blacksmith"},
		Meta: map[string]string{
			"go_version":         version.Go(),
			"blacksmith_version": version.Blacksmith(),
		},
	},
}

Defaults are the defaults options set for the supervisor. When not set, these values will automatically be applied.

var InterfaceSupervisor = "supervisor"

InterfaceSupervisor is the string representation for the supervisor interface.

Types

type Lock

type Lock struct {

	// Key is the id / name / key to acquire and release.
	Key string `json:"key"`
}

Lock holds information about a lock-key in the distributed system. This allows to acquire and release access to resources.

type Node

type Node struct {

	// ID is the unique identifier of the node to join.
	ID string `json:"id"`

	// Name is the name of the node to join.
	Name string `json:"name"`

	// Address is the address of the node to join.
	Address string `json:"address"`

	// Tags is a slice of tags related to the node.
	// They can be different from the services.
	Tags []string `json:"tags"`

	// Meta is a collection of meta-data related to the node.
	// They can be different from the services.
	Meta map[string]string `json:"meta"`
}

Node holds information about a node in a distributed environment the service running is about to join.

type Options

type Options struct {

	// From is used to set the desired supervisor adapter. It must be one of
	// AvailableAdapters.
	From string `json:"from,omitempty"`

	// Context is a free key-value dictionary that will be passed to the underlying
	// adapter.
	Context context.Context `json:"-"`

	// Join allows to attach the current instance to a node of the supervisor used.
	// Each instance shall be attached to a different node for distributed lock
	// mechanism.
	Join *Node `json:"node"`
}

Options is the options a user can pass to use the supervisor adapter.

type Registry

type Registry struct {

	// Services is a list of the services registered in the supervisor. Only the
	// services registered via Blacksmith are listed.
	Services []*Service `json:"services"`
}

Registry holds information about a service registry / mesh.

type Service

type Service struct {

	// ID is the unique identifier of the service.
	ID string `json:"id"`

	// Name is the name of the service.
	//
	// Example: "blacksmith-gateway"
	Name string `json:"name"`

	// Name is the version of the service being run at the moment.
	//
	// Example: "0.12.0"
	Version string `json:"version"`

	// Address is the address of the service.
	Address string `json:"address"`

	// Tags is a slice of tags related to the service.
	// They can be different from the node.
	Tags []string `json:"tags"`

	// Meta is a collection of meta-data related to the service.
	// They can be different from the node.
	Meta map[string]string `json:"meta"`

	// Nodes is a slice of nodes / instances registered for the service.
	Nodes []*Node `json:"nodes"`
}

Service is a service registered in the service registry.

type Supervisor

type Supervisor interface {

	// String returns the string representation of the adapter.
	//
	// Example: "consul"
	String() string

	// Options returns the options originally passed to the Options struct. This
	// can be used to validate and override user's options if necessary.
	Options() *Options

	// Init lets you initialize the Supervisor. It is useful to create a session
	// across nodes and register a service instance in the service registry.
	Init(*Toolkit, *Service) error

	// Shutdown let you gracefully shutdown a service in the Supervisor. It is
	// useful to destroy a session and deregister a service instance from the
	// service registry.
	Shutdown(*Toolkit, *Service) error

	// Lock allows to acquire a key in the semaphore. It returns true if the key
	// is successfully acquired.
	Lock(*Toolkit, *Lock) (bool, error)

	// Unlock allows to release a key from the semaphore. It returns true if the
	// key is successfully released.
	Unlock(*Toolkit, *Lock) (bool, error)

	// Health returns the status of the service registry.
	Health(*Toolkit) (*Registry, error)
}

Supervisor is the interface used to properly run Blacksmith applications in distributed environments. This allows strong data consistency and better infrastructure reliability.

type Toolkit

type Toolkit struct {

	// Logger gives access to the logrus Logger passed in options when creating the
	// Blacksmith application.
	Logger *logrus.Logger
}

Toolkit contains a suite of utilities and data to help the adapter successfully run the supervisor functions.