Documentation
¶
Overview ¶
Package application provides the core Contributoor functionality as a reusable library. It encapsulates beacon node connections, event processing, and metric collection.
Index ¶
- Variables
- type Application
- func (a *Application) BeaconNodes() map[string]*BeaconNodeInstance
- func (a *Application) ClockDrift() clockdrift.ClockDrift
- func (a *Application) Config() *config.Config
- func (a *Application) GetBeaconTraceIDs() []string
- func (a *Application) GetFirstHealthyBeacon() string
- func (a *Application) GetHealthStatus() HealthStatus
- func (a *Application) IsHealthy() bool
- func (a *Application) Logger() logrus.FieldLogger
- func (a *Application) Metrics(traceID string) *events.Metrics
- func (a *Application) Servers() *ServerManager
- func (a *Application) Start(ctx context.Context) error
- func (a *Application) Stop(ctx context.Context) error
- func (a *Application) WaitForHealthy(ctx context.Context, timeout time.Duration) bool
- type BeaconHealth
- type BeaconNodeInstance
- type HealthStatus
- type Options
- type ServerManager
- type TestOptions
Constants ¶
This section is empty.
Variables ¶
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 ¶
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 ¶
WithConfig sets the configuration.
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.