playbooklibrary

Documentation

Overview

Package playbooklibrary fetches the published playbook index (the `_index.yaml` file generated by `make generate-playbook-index`) and exposes it to the web UI so users can browse and import playbooks without leaving the app.

The service caches the index in memory and refreshes it on a TTL. On fetch failure it serves the previously cached copy if available so transient network blips don't break the Library tab.

Index

• Constants
• type CheckResult
• type CheckState
• type Config
  • func DefaultConfig() *Config
• type FolderEntry
• type Index
• type IndexResponse
• type LocalTestProvider
• type PlaybookEntry
• type Service
  • func NewService(cfg *Config, log logrus.FieldLogger, provider LocalTestProvider) Service

Constants

const (
	// DefaultIndexURL is the canonical index location for ethpandaops/assertoor.
	DefaultIndexURL = "https://raw.githubusercontent.com/ethpandaops/assertoor/master/playbooks/_index.yaml"

	// DefaultCacheTTL is how long a successfully fetched index is considered fresh.
	DefaultCacheTTL = 1 * time.Hour
)

Types

type CheckResult

type CheckResult struct {
	State       CheckState `json:"state"`
	RemoteID    string     `json:"remote_id"`
	RemoteName  string     `json:"remote_name"`
	RemoteURL   string     `json:"remote_url"`
	LocalTestID string     `json:"local_test_id,omitempty"`
	LocalName   string     `json:"local_name,omitempty"`
	LocalSource string     `json:"local_source,omitempty"`
}

CheckResult is returned by Service.Check.

type CheckState

type CheckState string

CheckState describes how a remote playbook compares to the locally registered test with the same id (if any).

const (
	// CheckStateAbsent means no local test has the same id.
	CheckStateAbsent CheckState = "absent"

	// CheckStateSame means a local test exists and its YAML matches
	// the remote source byte-for-byte (after whitespace trim).
	CheckStateSame CheckState = "same"

	// CheckStateDifferent means a local test exists but its YAML
	// differs from the remote source.
	CheckStateDifferent CheckState = "different"
)

type Config

type Config struct {
	// Enabled toggles the entire feature. When false the API handlers
	// short-circuit with "disabled" responses so the UI can hide the tab.
	Enabled bool `yaml:"enabled" json:"enabled"`

	// IndexURL points at the generated `_index.yaml`.
	IndexURL string `yaml:"indexURL" json:"indexURL"`

	// BaseURL is the URL prefix used to resolve `file` entries from the
	// index. If empty it is derived from IndexURL by stripping the
	// trailing filename (so the default index URL yields
	// `https://raw.githubusercontent.com/.../playbooks/`).
	BaseURL string `yaml:"baseURL,omitempty" json:"baseURL,omitempty"`

	// CacheTTL is how long a fetched index stays fresh before a
	// background re-fetch is triggered on the next request. Zero
	// means the default TTL is used.
	CacheTTL helper.Duration `yaml:"cacheTTL" json:"cacheTTL"`
}

Config controls the playbook library feature.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a config with the feature enabled and pointed at the upstream ethpandaops/assertoor index.

type FolderEntry

type FolderEntry struct {
	Path        string `yaml:"path" json:"path"`
	Name        string `yaml:"name" json:"name"`
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
}

FolderEntry describes a folder in the playbook tree. Path is relative to the playbooks root, with forward-slash separators.

type Index

type Index struct {
	Generated time.Time       `yaml:"generated" json:"generated"`
	Folders   []FolderEntry   `yaml:"folders" json:"folders"`
	Playbooks []PlaybookEntry `yaml:"playbooks" json:"playbooks"`
}

Index is the parsed _index.yaml.

type IndexResponse

type IndexResponse struct {
	Generated time.Time       `json:"generated"`
	BaseURL   string          `json:"base_url"`
	IndexURL  string          `json:"index_url"`
	Folders   []FolderEntry   `json:"folders"`
	Playbooks []PlaybookEntry `json:"playbooks"`
}

IndexResponse wraps the index with the resolved base URL for the frontend; the index itself doesn't carry that field.

type LocalTestProvider

type LocalTestProvider interface {
	// FindLocalYaml looks up the test with the given id and returns its
	// raw YAML source plus its display name. Returns ("", "", nil) when
	// no local test matches.
	FindLocalYaml(ctx context.Context, testID string) (yaml, name string, err error)
}

LocalTestProvider is the minimal interface the Service needs to compare remote playbooks against locally registered tests. It is satisfied by the assertoor coordinator's registry + YAML loader.

type PlaybookEntry

type PlaybookEntry struct {
	File        string   `yaml:"file" json:"file"`
	ID          string   `yaml:"id" json:"id"`
	Name        string   `yaml:"name" json:"name"`
	Description string   `yaml:"description,omitempty" json:"description,omitempty"`
	Version     string   `yaml:"version,omitempty" json:"version,omitempty"`
	Tags        []string `yaml:"tags,omitempty" json:"tags,omitempty"`
	Timeout     string   `yaml:"timeout,omitempty" json:"timeout,omitempty"`
}

PlaybookEntry describes a single playbook. File is relative to the playbooks root.

type Service

type Service interface {
	// Enabled reports whether the feature is configured.
	Enabled() bool

	// GetIndex returns the cached index, refreshing it if the TTL has
	// elapsed. On a refresh failure with a non-empty cache, the stale
	// copy is returned with a warning logged.
	GetIndex(ctx context.Context) (*IndexResponse, error)

	// Check fetches the remote YAML for the given relative file path,
	// looks up any local test with the same id, and returns how they
	// compare. The remote YAML is included in the result so the UI can
	// surface a diff when needed.
	Check(ctx context.Context, file string) (*CheckResult, string, error)
}

Service is the playbook library facade exposed to the API layer.

func NewService

func NewService(cfg *Config, log logrus.FieldLogger, provider LocalTestProvider) Service

NewService constructs a Service. Returns nil when cfg is nil or cfg.Enabled is false so callers can use the nil-check as their "feature disabled" gate.