Documentation ¶
Overview ¶
Package sputnik simplifies creation of satellite/sidecar processes for servers.
Modular monolith ¶
sputnik forces modular-monolith design:
- process created as set of independent asynchronously running blocks
Satellites blueprint ¶
sputnik supports common for all satellite processes functionality:
- ordered blocks initialization
- convenient negotiation between blocks
- server heartbeat
- graceful shutdown
Eats own dog food ¶
sputnik itself consists of 3 blocks:
- "initiator" - dispatcher of all blocks
- "finisher" - listener of external shutdown/exit events
- "connector" - connects/reconnects with server, provides this information to another blocks
Less You Know, the Better You Sleep ¶
sputnik knows nothing about internals of the process. It only assumes that server configuration and connection are required for functioning. This is the reason to define server connection and configuration as any. Use type assertions for "casting" to concrete interface/implementation.
Index ¶
- Constants
- func RegisterBlockFactory(name string, bf BlockFactory)
- func RegisterBlockFactoryInner(name string, bf BlockFactory, facts BlockFactories) error
- type Block
- type BlockCommunicator
- type BlockDescriptor
- type BlockFactories
- type BlockFactory
- type BlockOption
- type ConfFactory
- type DummyConnector
- type Finish
- type Init
- type Launch
- type Msg
- type OnMsg
- type OnServerConnect
- type OnServerDisconnect
- type Run
- type ServerConfiguration
- type ServerConnection
- type ServerConnector
- type ShootDown
- type Sputnik
- type SputnikOption
- func WithAppBlocks(appBlocks []BlockDescriptor) SputnikOption
- func WithBlockFactories(blkFacts BlockFactories) SputnikOption
- func WithConfFactory(cf ConfFactory) SputnikOption
- func WithConnector(cnt ServerConnector, to time.Duration) SputnikOption
- func WithFinisher(fbd BlockDescriptor) SputnikOption
Constants ¶
const ( InitiatorResponsibility = "initiator" DefaultConnectorName = "connector" DefaultConnectorResponsibility = "connector" DefaultFinisherName = "finisher" DefaultFinisherResponsibility = "finisher" )
const DefaultConnectorTimeout = time.Second * 5
const EchoBlockName = "echo"
Variables ¶
This section is empty.
Functions ¶
func RegisterBlockFactory ¶ added in v0.0.2
func RegisterBlockFactory(name string, bf BlockFactory)
BlockFactory registered in the process via RegisterBlockFactory Please pay attention that panic called for any error during registration.
Use init() for registration of BlockFactory
func init() { sputnik.RegisterBlockFactory("syslogPublisher", slpbFactory) }
func RegisterBlockFactoryInner ¶ added in v0.0.2
func RegisterBlockFactoryInner(name string, bf BlockFactory, facts BlockFactories) error
Types ¶
type Block ¶
type Block struct {
// contains filtered or unexported fields
}
Simplified Block life cycle:
- Init
- Run
- OnServerConnect
- [*]OnMsg
- OnServerDisconnect
- Finish
After Run order of callbacks will be unpredictable.
func NewBlock ¶ added in v0.0.3
func NewBlock(opts ...BlockOption) *Block
type BlockCommunicator ¶ added in v0.0.5
type BlockCommunicator interface { // // Get communicator of block by block's responsibility // Example - get BlockCommunicator of initiator: // initbl, ok := bc.Communicator(sputnik.InitiatorResponsibility) // Communicator(resp string) (bc BlockCommunicator, exists bool) // Identification of controlled block Descriptor() BlockDescriptor // Asynchronously send message to controlled block // true is returned if // - controlled block has OnMsg callback // - recipient of messages was not cancelled // - msg != nil Send(msg Msg) bool }
BlockCommunicator provides possibility for negotiation between blocks Block gets own communicator as parameter of Run
type BlockDescriptor ¶ added in v0.0.2
Block has Name (analog of golang type) and Responsibility (instance of specific block) This separation allows to run simultaneously blocks with the same Name. Other possibility - blocks with different name but with the same responsibility, e.g. different implementation of "finisher" depends on environment.
func ConnectorDescriptor ¶ added in v0.0.3
func ConnectorDescriptor() BlockDescriptor
func FinisherDescriptor ¶ added in v0.0.2
func FinisherDescriptor() BlockDescriptor
type BlockFactories ¶ added in v0.0.2
type BlockFactories map[string]BlockFactory
func DefaultFactories ¶ added in v0.0.2
func DefaultFactories() BlockFactories
type BlockFactory ¶ added in v0.0.2
type BlockFactory func() *Block
BlockFactory should be provided for every block in the process
func EchoBlockFactory ¶ added in v0.0.7
func EchoBlockFactory(q *kissngoqueue.Queue[Msg]) BlockFactory
func Factory ¶ added in v0.0.3
func Factory(name string) (BlockFactory, error)
type BlockOption ¶ added in v0.0.3
type BlockOption func(b *Block)
func WithFinish ¶ added in v0.0.3
func WithFinish(f Finish) BlockOption
func WithInit ¶ added in v0.0.3
func WithInit(f Init) BlockOption
func WithOnConnect ¶ added in v0.0.3
func WithOnConnect(f OnServerConnect) BlockOption
func WithOnDisconnect ¶ added in v0.0.5
func WithOnDisconnect(f OnServerDisconnect) BlockOption
func WithOnMsg ¶ added in v0.0.3
func WithOnMsg(f OnMsg) BlockOption
func WithRun ¶ added in v0.0.3
func WithRun(f Run) BlockOption
type ConfFactory ¶ added in v0.0.3
Configuration Factory
type DummyConnector ¶ added in v0.0.6
type DummyConnector struct {
// contains filtered or unexported fields
}
Connector's plugin used for debugging/testing
func (*DummyConnector) Connect ¶ added in v0.0.6
func (c *DummyConnector) Connect(cf ConfFactory) (conn ServerConnection, err error)
func (*DummyConnector) Disconnect ¶ added in v0.0.6
func (c *DummyConnector) Disconnect()
func (*DummyConnector) IsConnected ¶ added in v0.0.6
func (c *DummyConnector) IsConnected() bool
func (*DummyConnector) SetState ¶ added in v0.0.6
func (c *DummyConnector) SetState(connected bool)
Allows to simulate state of the connection
type Finish ¶
type Finish func(init bool)
Finish callback is executed by sputnik:
- during initialization of the process if init of another block failed (init == true)
- during shutdown of the process (init == false)
Blocks are finished in reverse of initialization order.
type Init ¶
type Init func(cf ConfFactory) error
Block has set of the callbacks:
- mandatory: Init|Run|Finish
- optional: OnServerConnect|OnServerDisconnect|OnMsg
Init callback is executed by sputnik once during initialization. Blocks are initialized in sequenced order according to configuration. Some rules :
- don't run hard processing within Init
- don't work with server till call of OnServerConnect
type Msg ¶ added in v0.0.2
Because asynchronous nature of blocks, negotiation between blocks done using 'messages' Message may be command|query|event|update|... Developers of blocks should agree on content of messages. sputnik doesn't force specific format of the message with one exception: key of the map should not start from "__". This prefix is used by sputnik for house-keeping values.
func FinishedMsg ¶ added in v0.0.5
func FinishedMsg() Msg
type OnMsg ¶ added in v0.0.2
type OnMsg func(msg Msg)
Optional OnMsg callback is executed by sputnik as result of receiving Msg. Block can send message to itself. Unlike other callbacks, OnMsg called sequentially one by one from the same goroutine.
type OnServerConnect ¶
type OnServerConnect func(connection ServerConnection)
Optional OnServerConnect callback is executed by sputnik after successful connection to server.
type OnServerDisconnect ¶
type OnServerDisconnect func()
Optional OnServerDisconnect callback is executed by sputnik when previously connected server disconnects.
type Run ¶
type Run func(communicator BlockCommunicator)
After successful initialization of ALL blocks, sputnik creates goroutine and calls Run Other callbacks will be executed on another goroutines After Run block is allowed to negotiate with another blocks of the process via BlockCommunicator
type ServerConnection ¶ added in v0.0.4
type ServerConnection any
type ServerConnector ¶ added in v0.0.4
type ServerConnector interface { // Connects to the server and return connection to server // If connection failed, returns error. // ' Connect' for already connected // and still not brocken connection should // return the same value returned in previous // successful call(s) and nil error Connect(cf ConfFactory) (conn ServerConnection, err error) // Returns false if // - was not connected at all // - was connected, but connection is brocken // True returned if // - connected and connection is alive IsConnected() bool // If connection is alive closes it Disconnect() }
type Sputnik ¶ added in v0.0.3
type Sputnik struct {
// contains filtered or unexported fields
}
func NewSputnik ¶ added in v0.0.3
func NewSputnik(opts ...SputnikOption) (*Sputnik, error)
func (Sputnik) Prepare ¶ added in v0.0.3
Creates and initializes all blocks.
If creation and initialization of any block failed:
Finish is called on all already initialized blocks
Order of finish - reversal of initialization
= Returned error describes reason of the failure
Otherwise returned 2 functions for sputnik management:
lfn - Launch of the sputnik , exit from this function will be after signal for shutdown of the process or after call of second returned function (see below)
st - ShootDown of sputnik - abort flight
type SputnikOption ¶ added in v0.0.3
type SputnikOption func(sp *Sputnik)
func WithAppBlocks ¶ added in v0.0.3
func WithAppBlocks(appBlocks []BlockDescriptor) SputnikOption
func WithBlockFactories ¶ added in v0.0.3
func WithBlockFactories(blkFacts BlockFactories) SputnikOption
func WithConfFactory ¶ added in v0.0.3
func WithConfFactory(cf ConfFactory) SputnikOption
func WithConnector ¶ added in v0.0.3
func WithConnector(cnt ServerConnector, to time.Duration) SputnikOption
func WithFinisher ¶ added in v0.0.3
func WithFinisher(fbd BlockDescriptor) SputnikOption