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, scheduler, or CLI 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 Driver
• type Lock
• type Options
• type Semaphore
• type Service
• type Supervisor
• type Toolkit

Variables

var Defaults = &Options{}

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 Driver

type Driver string

Driver is a custom type allowing the user to only pass supported drivers when configuring the supervisor adapter.

var DriverConsul Driver = "consul"

DriverConsul is used to leverage Consul as the supervisor adapter.

var DriverPostgreSQL Driver = "postgres"

DriverPostgreSQL is used to leverage PostgreSQL as the supervisor adapter.

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 Options

type Options struct {

	// From is used to set the desired driver for the supervisor adapter.
	From Driver `json:"from,omitempty"`

	// Connection is the connection string to connect to the supervisor.
	Connection string `json:"-"`
}

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

type Semaphore

type Semaphore struct {

	// Key is the id / name / key looked up. Even if IsApplicable is false, Key is
	// set to the appropriate key name as if it were applicable.
	Key string `json:"key"`

	// IsApplicable informs the client if a semaphore is needed for the given
	// resource. As an example, the supervisor is leveraged for CDC and CRON triggers
	// but not for HTTP or subscription ones.
	IsApplicable bool `json:"is_applicable"`

	// IsAcquired informs if the key is currently in use. It can nil if the supervisor
	// adapter encountered an error while looking up the key and therefore does not
	// know its status. It can also be nil if the key to look up does not need to
	// acquire a lock in the semaphore (in other words, if IsApplicable is false).
	IsAcquired *bool `json:"is_acquired,omitempty"`

	// AcquirerName is the name of the acquirer currently using the key. It is empty
	// if the key is not in use.
	AcquirerName string `json:"acquirer_name,omitempty"`

	// AcquirerAddress is the address of the acquirer currently using the key. It
	// is empty if the key is not in use.
	AcquirerAddress string `json:"acquirer_address,omitempty"`

	// SessionID is the ID of the session started by the running service or CLI
	// currently using the key. It is empty if the key is not in use.
	SessionID string `json:"session_id,omitempty"`
}

Semaphore holds details about a semaphore in the supervisor. This is returned by the supervisor for a given Lock's status. These details are also included in some of the admin API endpoints to inform clients about the semaphore of a given trigger, action, or migration.

type Service

type Service struct {

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

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

	// Version is the Blacksmith version being run at the moment by the service.
	//
	// Example: "0.18.0"
	Version string `json:"version"`

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

	// Tags is a slice of tags related to the service.
	Tags []string `json:"tags"`

	// Meta is a collection of meta-data related to the service.
	Meta map[string]string `json:"meta"`
}

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 if
	// applicable.
	Init(*Toolkit) error

	// Shutdown lets you gracefully shutdown a service in the Supervisor. It is
	// useful to destroy a session and deregister a service instance from the
	// service registry if applicable.
	Shutdown(*Toolkit) 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)

	// Status returns the semaphore status for a given key.
	Status(*Toolkit, *Lock) (*Semaphore, 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

	// Service holds details about the service accessing the semaphore. It shall be
	// used by the adapter to allow (or not) the lock and unlock of a key. A running
	// service can not lock or unlock resources already used by an other service.
	Service *Service
}

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