services

Documentation

Overview

Package services contain the key components of the Chainlink node. This includes the Application, JobRunner, LogListener, and Scheduler.

Application

The Application is the main component used for starting and stopping the Chainlink node.

JobRunner

The JobRunner keeps track of Runs within a Job and ensures that they're executed in order. Within each Run, the tasks are also executed from the JobRunner.

JobSubscriber

The JobSubscriber coordinates running job events with the EventLog in the Store, and also subscribes to the given address on the Ethereum blockchain.

Scheduler

The Scheduler ensures that recurring events are executed according to their schedule, and one-time events occur only when the specified time has passed.

Index

• func CloseAll(cs ...io.Closer) error
• func MultiCloser[C io.Closer](cs []C) io.Closer
• type CheckFunc
• type Checkable
• type Checker
  • func NewChecker() Checker
• type Config
• type Meta
• type MultiStart
  • func (m *MultiStart) Close() (err error)
  • func (m *MultiStart) CloseBecause(reason error) (err error)
  • func (m *MultiStart) Start(ctx context.Context, srvcs ...StartClose) (err error)
• type Nurse
  • func NewNurse(cfg Config, log logger.Logger) *Nurse
  • func (n *Nurse) AddCheck(reason string, checkFunc CheckFunc)
  • func (n *Nurse) Close() error
  • func (n *Nurse) GatherVitals(reason string, meta Meta)
  • func (n *Nurse) Start() error
• type ServiceCtx
• type StartClose
• type Status

Examples

• MultiCloser
• MultiStart

Functions

func CloseAll

func CloseAll(cs ...io.Closer) error

CloseAll closes all elements concurrently. Use this when you have various different types of io.Closer.

func MultiCloser

func MultiCloser[C io.Closer](cs []C) io.Closer

MultiCloser returns an io.Closer which closes all elements concurrently. Use this when you have a slice of a type which implements io.Closer. []io.Closer can be cast directly to MultiCloser.

Example

ctx := context.Background()

f1 := CloseFailure("f")
f2 := CloseFailure("f")
cs := []CloseFailure{f1, f2}

var ms MultiStart
if err := ms.Start(ctx, f1, f2); err != nil {
	fmt.Println(err)
	return
}
mc := MultiCloser(cs)
if err := mc.Close(); err != nil {
	fmt.Println(err)
}

Output:

f started
f started
f close failure
f close failure
failed to close: f; failed to close: f

Types

type CheckFunc

type CheckFunc func() (unwell bool, meta Meta)

type Checkable

type Checkable interface {
	// Ready should return nil if ready, or an error message otherwise.
	Ready() error
	// HealthReport returns a full health report of the callee including it's dependencies.
	// key is the dep name, value is nil if healthy, or error message otherwise.
	HealthReport() map[string]error
}

Checkable should be implemented by any type requiring health checks. From the k8s docs: > ready means it’s initialized and healthy means that it can accept traffic in kubernetes See: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/

type Checker

type Checker interface {
	// Register a service for health checks.
	Register(name string, service Checkable) error
	// Unregister a service.
	Unregister(name string) error
	// IsReady returns the current readiness of the system.
	// A system is considered ready if all checks are passing (no errors)
	IsReady() (ready bool, errors map[string]error)
	// IsHealthy returns the current health of the system.
	// A system is considered healthy if all checks are passing (no errors)
	IsHealthy() (healthy bool, errors map[string]error)

	Start() error
	Close() error
}

Checker provides a service which can be probed for system health.

func NewChecker

func NewChecker() Checker

type Config

type Config interface {
	BlockProfileRate() int
	CPUProfileRate() int
	GatherDuration() models.Duration
	GatherTraceDuration() models.Duration
	GoroutineThreshold() int
	MaxProfileSize() utils.FileSize
	MemProfileRate() int
	MemThreshold() utils.FileSize
	MutexProfileFraction() int
	PollInterval() models.Duration
	ProfileRoot() string
}

type Meta

type Meta map[string]interface{}

type MultiStart

type MultiStart struct {
	// contains filtered or unexported fields
}

MultiStart is a utility for starting multiple services together. The set of started services is tracked internally, so that they can be closed if any single service fails to start.

Example

ctx := context.Background()

a := Healthy("a")
b := CloseFailure("b")
c := WontStart("c")

var ms MultiStart
if err := ms.Start(ctx, a, b, c); err != nil {
	fmt.Println(err)
}

Output:

a started
b started
c start failure
b close failure
a closed
failed to start: c; failed to close: b

func (*MultiStart) Close

func (m *MultiStart) Close() (err error)

Close closes all started services, in reverse order.

func (*MultiStart) CloseBecause

func (m *MultiStart) CloseBecause(reason error) (err error)

CloseBecause calls Close and returns reason along with any additional errors.

func (*MultiStart) Start

func (m *MultiStart) Start(ctx context.Context, srvcs ...StartClose) (err error)

Start attempts to Start all services. If any service fails to start, the previously started services will be Closed, and an error returned.

type Nurse

type Nurse struct {
	utils.StartStopOnce
	// contains filtered or unexported fields
}

func NewNurse

func NewNurse(cfg Config, log logger.Logger) *Nurse

func (*Nurse) AddCheck

func (n *Nurse) AddCheck(reason string, checkFunc CheckFunc)

func (*Nurse) Close

func (n *Nurse) Close() error

func (*Nurse) GatherVitals

func (n *Nurse) GatherVitals(reason string, meta Meta)

func (*Nurse) Start

func (n *Nurse) Start() error

type ServiceCtx

type ServiceCtx interface {
	// Start the service. Must quit immediately if the context is cancelled.
	// The given context applies to Start function only and must not be retained.
	Start(context.Context) error
	// Close stops the Service.
	// Invariants: Usually after this call the Service cannot be started
	// again, you need to build a new Service to do so.
	Close() error

	// Name returns the fully qualified name of the service
	Name() string

	Checkable
}

ServiceCtx represents a long-running service inside the Application.

Typically, a ServiceCtx will leverage utils.StartStopOnce to implement these calls in a safe manner.

Template

Mockable Foo service with a run loop

//go:generate mockery --quiet --name Foo --output ../internal/mocks/ --case=underscore
type (
	// Expose a public interface so we can mock the service.
	Foo interface {
		service.ServiceCtx

		// ...
	}

	foo struct {
		// ...

		stop chan struct{}
		done chan struct{}

		utils.StartStopOnce
	}
)

var _ Foo = (*foo)(nil)

func NewFoo() Foo {
	f := &foo{
		// ...
	}

	return f
}

func (f *foo) Start(ctx context.Context) error {
	return f.StartOnce("Foo", func() error {
		go f.run()

		return nil
	})
}

func (f *foo) Close() error {
	return f.StopOnce("Foo", func() error {
		// trigger goroutine cleanup
		close(f.stop)
		// wait for cleanup to complete
		<-f.done
		return nil
	})
}

func (f *foo) run() {
	// signal cleanup completion
	defer close(f.done)

	for {
		select {
		// ...
		case <-f.stop:
			// stop the routine
			return
		}
	}

}

type StartClose

type StartClose interface {
	Start(context.Context) error
	Close() error
}

StartClose is a subset of the ServiceCtx interface.

type Status

type Status string

const (
	StatusPassing Status = "passing"
	StatusFailing Status = "failing"
)