application

package
v0.0.71 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 30, 2025 License: GPL-3.0 Imports: 19 Imported by: 0

Documentation

Overview

Package application provides the core Contributoor functionality as a reusable library. It encapsulates beacon node connections, event processing, and metric collection.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrConfigRequired is returned when no configuration is provided.
	ErrConfigRequired = errors.New("configuration is required")

	// ErrNoBeaconNodes is returned when no beacon nodes are configured.
	ErrNoBeaconNodes = errors.New("no beacon nodes configured")

	// ErrAllBeaconsFailed is returned when all beacon nodes fail to connect.
	ErrAllBeaconsFailed = errors.New("all beacon nodes failed to connect")
)

Common errors returned by the application package.

Functions

This section is empty.

Types

type Application

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

Application represents a Contributoor instance with all its components. It manages beacon node connections, event processing, metrics collection, and provides HTTP endpoints for health checks and metrics.

func New

func New(opts Options) (*Application, error)

New creates a new Application instance with the provided options. It validates the configuration and sets up logging but does not start any services. Use Start() to begin processing.

func NewTestApplication

func NewTestApplication(t *testing.T, opts TestOptions) *Application

NewTestApplication creates an Application configured for testing. It automatically registers cleanup functions with testing.T.

func (*Application) BeaconNodes

func (a *Application) BeaconNodes() map[string]*BeaconNodeInstance

BeaconNodes returns the map of beacon node instances. This is useful for testing and monitoring.

func (*Application) ClockDrift

func (a *Application) ClockDrift() clockdrift.ClockDrift

ClockDrift returns the clock drift service instance. This is useful for testing or external monitoring.

func (*Application) Config

func (a *Application) Config() *config.Config

Config returns the application configuration.

func (*Application) GetBeaconTraceIDs

func (a *Application) GetBeaconTraceIDs() []string

GetBeaconTraceIDs returns a slice of all beacon trace IDs. Useful for tests that need to verify specific beacons.

func (*Application) GetFirstHealthyBeacon

func (a *Application) GetFirstHealthyBeacon() string

GetFirstHealthyBeacon returns the trace ID of the first healthy beacon found. Returns empty string if no healthy beacons exist.

func (*Application) GetHealthStatus

func (a *Application) GetHealthStatus() HealthStatus

GetHealthStatus returns detailed health information about the application.

func (*Application) IsHealthy

func (a *Application) IsHealthy() bool

IsHealthy returns true if at least one beacon node is healthy and connected.

func (*Application) Logger

func (a *Application) Logger() logrus.FieldLogger

Logger returns the application logger.

func (*Application) Metrics

func (a *Application) Metrics(traceID string) *events.Metrics

Metrics returns the metrics for a specific beacon node by trace ID. Returns nil if the trace ID is not found.

func (*Application) Servers

func (a *Application) Servers() *ServerManager

Servers returns the server manager for testing purposes.

func (*Application) Start

func (a *Application) Start(ctx context.Context) error

Start initializes and starts all components of the application. It starts HTTP servers, connects to beacon nodes, and begins event processing.

func (*Application) Stop

func (a *Application) Stop(ctx context.Context) error

Stop gracefully shuts down all components of the application.

func (*Application) WaitForHealthy

func (a *Application) WaitForHealthy(ctx context.Context, timeout time.Duration) bool

WaitForHealthy waits for at least one beacon node to become healthy. Returns true if healthy within the timeout, false otherwise.

type BeaconHealth

type BeaconHealth struct {
	Connected bool   `json:"connected"`
	Healthy   bool   `json:"healthy"`
	Address   string `json:"address"`
}

BeaconHealth represents the health status of a single beacon node.

type BeaconNodeInstance

type BeaconNodeInstance struct {
	Node         ethereum.BeaconNodeAPI
	Cache        *events.DuplicateCache
	Sinks        []sinks.ContributoorSink
	Metrics      *events.Metrics
	Summary      *events.Summary
	Address      string // The beacon node's address
	TopicManager ethereum.TopicManager
	// contains filtered or unexported fields
}

BeaconNodeInstance holds all components related to a single beacon node connection.

func (*BeaconNodeInstance) RestartWithoutSingleAttestation added in v0.0.69

func (b *BeaconNodeInstance) RestartWithoutSingleAttestation(ctx context.Context) error

RestartWithoutSingleAttestation restarts the beacon node without the single_attestation topic. This method ensures proper cleanup of the old beacon instance before creating a new one. Resources that are cleaned up: - Summary goroutine (cancelled via summaryCancel). - Monitoring goroutines (signaled via stopMonitor channel). - Beacon node connection (stopped via Node.Stop()). - Old Metrics and Summary instances (replaced with new ones). Resources that are reused: - Cache (shared across restarts). - Sinks (shared across restarts). - Log instance.

type HealthStatus

type HealthStatus struct {
	Healthy     bool                    `json:"healthy"`
	BeaconNodes map[string]BeaconHealth `json:"beacon_nodes"` //nolint:tagliatelle // upstream definition.
}

HealthStatus represents the health status of the application.

type Options

type Options struct {
	// Config is the Contributoor configuration. This field is required.
	Config *config.Config

	// Logger is the logger to use. If nil, a default logger will be created.
	Logger logrus.FieldLogger

	// Debug enables debug mode which uses stdout sink instead of the configured output.
	Debug bool

	// ClockDrift is an optional clock drift service. If nil, one will be created.
	ClockDrift clockdrift.ClockDrift

	// NTPServer is the NTP server to use for clock drift detection.
	// Defaults to "pool.ntp.org" if not specified.
	NTPServer string

	// ClockDriftSyncInterval is the interval for syncing with NTP.
	// Defaults to 5 minutes if not specified.
	ClockDriftSyncInterval time.Duration
}

Options contains all configuration options for creating an Application. Config is required, all other fields are optional and will use defaults if not provided.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns Options with sensible defaults. You must still provide a Config before creating an Application.

func (Options) WithClockDrift

func (o Options) WithClockDrift(cd clockdrift.ClockDrift) Options

WithClockDrift sets the clock drift service.

func (Options) WithConfig

func (o Options) WithConfig(cfg *config.Config) Options

WithConfig sets the configuration.

func (Options) WithDebug

func (o Options) WithDebug(debug bool) Options

WithDebug enables or disables debug mode.

func (Options) WithLogger

func (o Options) WithLogger(logger logrus.FieldLogger) Options

WithLogger sets the logger.

type ServerManager

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

ServerManager handles HTTP server lifecycle for metrics, pprof, and health checks.

type TestOptions

type TestOptions struct {
	// T is the testing context, used for cleanup registration
	T *testing.T

	// Config to use. If nil, a minimal test config will be created
	Config *config.Config

	// Logger to use. If nil, a test logger will be created
	Logger logrus.FieldLogger

	// Debug mode
	Debug bool

	// Custom beacon addresses. If empty, uses localhost:5052
	BeaconAddresses []string
}

TestOptions provides convenient options for creating Applications in tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL