status

README

Docs: link

Documentation

Overview

Package status is a RoadRunner plugin that exposes HTTP endpoints and RPC methods for monitoring the health, readiness, and job queue state of registered plugins.

The plugin starts an HTTP server with three endpoints:

• /health – returns the aggregated health status of every plugin that implements the Checker interface.
• /ready – returns the readiness status of every plugin that implements the Readiness interface.
• /jobs – returns the state of job pipelines from a plugin that implements the JobsChecker interface.

During graceful shutdown the endpoints respond with 503 Service Unavailable (or a configurable status code) so that external load balancers can drain traffic before the process exits.

An RPC service is also registered, providing Status and Ready methods for programmatic access from RoadRunner workers or CLI tools.

Index

• Constants
• type Checker
• type Config
  • func (c *Config) InitDefaults()
• type Configurer
• type Health
  • func NewHealthHandler(sr map[string]Checker, shutdownInitiated *atomic.Pointer[bool], ...) *Health
  • func (rd *Health) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Jobs
  • func NewJobsHandler(jc JobsChecker, shutdownInitiated *atomic.Pointer[bool], log *zap.Logger, ...) *Jobs
  • func (jb *Jobs) ServeHTTP(w http.ResponseWriter, _ *http.Request)
• type JobsChecker
• type JobsReport
• type Logger
• type Plugin
  • func (c *Plugin) Collects() []*dep.In
  • func (c *Plugin) Init(cfg Configurer, log Logger) error
  • func (c *Plugin) Name() string
  • func (c *Plugin) RPC() any
  • func (c *Plugin) Serve() chan error
  • func (c *Plugin) Stop(_ context.Context) error
  • func (c *Plugin) StopHTTPServer()
• type Readiness
• type Ready
  • func NewReadyHandler(sr map[string]Readiness, shutdownInitiated *atomic.Pointer[bool], ...) *Ready
  • func (rd *Ready) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Report

Constants

const (
	// PluginName declares public plugin name.
	PluginName = "status"
)

Types

type Checker

type Checker interface {
	Status() (*status.Status, error)
	Name() string
}

Checker interface used to get the latest status from the plugin

type Config

type Config struct {
	// Address of the http server
	Address string
	// Time to wait for a health check response.
	CheckTimeout int `mapstructure:"check_timeout"`
	// Status code returned in case of fail, 503 by default
	UnavailableStatusCode int `mapstructure:"unavailable_status_code"`
}

Config is the configuration reference for the Status plugin

func (*Config) InitDefaults

func (c *Config) InitDefaults()

InitDefaults configuration options

type Configurer

type Configurer interface {
	// UnmarshalKey takes a single key and unmarshal it into a Struct.
	UnmarshalKey(name string, out any) error
	// Has checks if a config section exists.
	Has(name string) bool
}

type Health

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

func NewHealthHandler

func NewHealthHandler(sr map[string]Checker, shutdownInitiated *atomic.Pointer[bool], log *zap.Logger, usc int) *Health

func (*Health) ServeHTTP

func (rd *Health) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Jobs

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

func NewJobsHandler

func NewJobsHandler(jc JobsChecker, shutdownInitiated *atomic.Pointer[bool], log *zap.Logger, usc int) *Jobs

func (*Jobs) ServeHTTP

func (jb *Jobs) ServeHTTP(w http.ResponseWriter, _ *http.Request)

type JobsChecker

type JobsChecker interface {
	JobsState(ctx context.Context) ([]*jobsApi.State, error)
	Name() string
}

type JobsReport

type JobsReport struct {
	Pipeline     string `json:"pipeline"`
	Priority     uint64 `json:"priority"`
	Ready        bool   `json:"ready"`
	Queue        string `json:"queue"`
	Active       int64  `json:"active"`
	Delayed      int64  `json:"delayed"`
	Reserved     int64  `json:"reserved"`
	Driver       string `json:"driver"`
	ErrorMessage string `json:"error_message"`
}

type Logger

type Logger interface {
	NamedLogger(name string) *zap.Logger
}

type Plugin

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

func (*Plugin) Collects

func (c *Plugin) Collects() []*dep.In

Collects declare services to be collected.

func (*Plugin) Init

func (c *Plugin) Init(cfg Configurer, log Logger) error

func (*Plugin) Name

func (c *Plugin) Name() string

Name of the service.

func (*Plugin) RPC

func (c *Plugin) RPC() any

RPC returns associated rpc service.

func (*Plugin) Serve

func (c *Plugin) Serve() chan error

func (*Plugin) Stop

func (c *Plugin) Stop(_ context.Context) error

func (*Plugin) StopHTTPServer

func (c *Plugin) StopHTTPServer()

StopHTTPServer stops the http server, used only for TEST purposes

type Readiness

type Readiness interface {
	Ready() (*status.Status, error)
	Name() string
}

Readiness interface used to get readiness status from the plugin that means that a worker pool inside the plugin has 1+ plugins which are ready to work at the particular moment

type Ready

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

func NewReadyHandler

func NewReadyHandler(sr map[string]Readiness, shutdownInitiated *atomic.Pointer[bool], log *zap.Logger, usc int) *Ready

func (*Ready) ServeHTTP

func (rd *Ready) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Report

type Report struct {
	PluginName   string `json:"plugin_name"`
	ErrorMessage string `json:"error_message"`
	StatusCode   int    `json:"status_code"`
}