components

package
v0.5.9 Latest Latest
Warning

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

 Go to latest Published: May 11, 2024 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package components provides support for processing components from a status page API powered by Atlassian Statuspage.

Index

Constants

View Source 
const (
	ComponentStatusDegradedPerformance string = "degraded_performance"
	ComponentStatusPartialOutage       string = "partial_outage"
	ComponentStatusMajorOutage         string = "major_outage"
	ComponentStatusUnderMaintenance    string = "under_maintenance"
	ComponentStatusOperational         string = "operational"

	// ComponentStatusUnknown is not an official component status, but rather
	// an indication that something went wrong when evaluating a component's
	// status.
	ComponentStatusUnknown string = "UNKNOWN"
)

Component status enums. https://developer.statuspage.io/#operation/getPagesPageIdComponents

View Source 
const (
	// ComponentIDRegex is an observed pattern for component ID values. For
	// example, the Box.com Statuspage has a component Group named "Mobile
	// Applications" with an ID of "g58jskvcnlh8" (no quotes). This is 12
	// characters long and is composed of lowercase ascii characters and the
	// numbers 0 through 9.
	ComponentIDRegex string = "[a-z0-9]{12}"

	// ComponentIDLength is the consistent length of observed component ID
	// values.
	ComponentIDLength int = 12
)

Component IDs are officially documented as "Identifier for component" with a value of type string. Neither the ID length nor the specific character pattern is provided in developer documentation, but after reviewing the ID values used by many Statuspage powered sites the following details are believed to accurately describe component IDs.

View Source 
const (
	PrepTaskParseURL        string = "parse URL"
	PrepTaskPrepareRequest  string = "prepare request"
	PrepTaskDecode          string = "decode JSON data"
	PrepTaskSubmitRequest   string = "submit request"
	PrepTaskProcessResponse string = "process response"
)

Prep tasks for creation of a components Set.

View Source 
const ComponentStartDateLayout = "2006-01-02"

ComponentStartDateLayout is the time format/layout for the start_date field of a Statuspage component.

Variables

View Source 
var ErrComponentGroupNotFound = errors.New(
	"component group not found",
)

ErrComponentGroupNotFound indicates that a component group was not found when attempting to apply a given filter to a components set or when searching by name or id values.

View Source 
var ErrComponentIsNotComponentGroup = errors.New(
	"component is not a component group",
)

ErrComponentIsNotComponentGroup indicates that a specified component was found to not be a component group when attempting to apply a given filter to a components set.

View Source 
var ErrComponentIsNotValidSubcomponent = errors.New(
	"component is not a member of specified group",
)

ErrComponentIsNotValidSubcomponent indicates that a specified component was found to not be a member of a specified component group when attempting to apply a given filter to a components set.

View Source 
var ErrComponentNotFound = errors.New(
	"component not found",
)

ErrComponentNotFound indicates that a component was not found when attempting to apply a given filter to a components set or when searching by name or id values.

View Source 
var ErrComponentSetFilterEmpty = errors.New(
	"given component set filter is empty",
)

ErrComponentSetFilterEmpty indicates that a given components set filter is empty.

View Source 
var ErrComponentSetFilterInvalid = errors.New(
	"given component set filter is invalid",
)

ErrComponentSetFilterInvalid indicates that a given components set filter is in an unknown or invalid state. This error condition is unlikely to occur.

View Source 
var ErrComponentSetFilterWhitespaceComponentsField = errors.New(
	"given component set filter contains whitespace only components list value",
)

ErrComponentSetFilterWhitespaceComponentsField indicates that a given components set filter contains a whitespace only components list field value.

View Source 
var ErrComponentSetFilterWhitespaceGroupField = errors.New(
	"given component set filter contains whitespace only group value",
)

ErrComponentSetFilterWhitespaceGroupField indicates that a given components set filter contains a whitespace only group field value.

View Source 
var ErrComponentSetValidationFailed = errors.New(
	"decoded components endpoint JSON data validation failed",
)

ErrComponentSetValidationFailed indicates that validating decode JSON data has failed.

View Source 
var ErrComponentStatusDegradedPerformance = errors.New(
	"component has degraded performance status",
)

ErrComponentStatusDegradedPerformance indicates that a component was found to have a degraded performance status.

View Source 
var ErrComponentStatusMajorOutage = errors.New(
	"component has major outage status",
)

ErrComponentStatusMajorOutage indicates that a component was found to have a major outage status.

View Source 
var ErrComponentStatusPartialOutage = errors.New(
	"component has partial outage status",
)

ErrComponentStatusPartialOutage indicates that a component was found to have a partial outage status.

View Source 
var ErrComponentStatusUnderMaintenance = errors.New(
	"component has under maintenance status",
)

ErrComponentStatusUnderMaintenance indicates that a component was found to have an under maintenance status.

View Source 
var ErrComponentWithProblemStatusNotExcluded = errors.New(
	"component with non-operational status not excluded from evaluation",
)

ErrComponentWithProblemStatusNotExcluded indicates that a component with a non-operational status was not excluded from evaluation. This is a user-facing error, intended for display in detailed output.

View Source 
var ErrResponseOutsideRange = errors.New(
	"response is outside acceptable range",
)

ErrResponseOutsideRange indicates that a response was received which falls outside of an acceptable range.

View Source 
var ErrSubcomponentNotFound = errors.New(
	"subcomponent not found",
)

ErrSubcomponentNotFound indicates that a subcomponent was not found when attempting to apply a given filter to a components set or when searching by name or id values.

Functions

func ComponentStatusToServiceState 

func ComponentStatusToServiceState(componentStatus string) nagios.ServiceState

ComponentStatusToServiceState converts a Statuspage Status (e.g., "degraded_performance", "under_maintenance") to a Nagios ServiceState.

func DisableLogging 

func DisableLogging()

DisableLogging reapplies default package-level logging settings of muting all logging output.

func EnableLogging 

func EnableLogging()

EnableLogging enables logging output from this package. Output is muted by default unless explicitly requested (by calling this function).

func ServiceStateToComponentStatuses 

func ServiceStateToComponentStatuses(serviceState nagios.ServiceState) []string

ServiceStateToComponentStatuses converts a given Nagios ServiceState to a collection of component statuses that are considered to be an equivalent value.

Types

type Component 

type Component struct {

	// ComponentIDs is either a collection of individual subcomponent (aka,
	// "child") ID values when this component represents a component group,
	// otherwise is not present in the feed data.
	ComponentIDs []string `json:"components,omitempty"`

	// Description is additional human readable details for a component
	// intended to expand upon the component name. This is used as mouseover
	// or "hover text" for the component. This value may be null in the JSON
	// feed.
	Description statuspage.NullString `json:"description"`

	// GroupID is the component group (aka, "parent") identifier if this is a
	// subcomponent (aka, "child") or an empty string if this component is a
	// component group.
	GroupID statuspage.NullString `json:"group_id"`

	// Id is the unique identifier for the component.
	ID string `json:"id"`

	// Name is the human readable text shown on the Statuspage for a
	// component. The uniqueness of this value is not enforced, even for two
	// components at the same level, whether as members of a component group
	// or as a top-level component.
	Name string `json:"name"`

	// Status indicates the current status of the component. Uses a fixed set
	// of enum values.
	Status string `json:"status"`

	// PageID is the unique identifier for the Statuspage associated with the
	// components feed.
	PageID string `json:"page_id"`

	// Position is the order a component will appear on the page.
	Position int `json:"position"`

	// The creation time for this component. This value does not appear to be
	// updated once set.
	CreatedAt time.Time `json:"created_at"`

	// StartDate indicates the date this component started being used. By
	// default, when a new component is added the date will be set the current
	// date. This value is used to provide a representation of historical
	// uptime.
	//
	// This value may be null. See the ComponentStartDateLayout for the
	// specific format used by this date. Use the IsSet() method to determine
	// whether the component has this field set.
	StartDate ComponentStartDate `json:"start_date"`

	// UpdatedAt indicates when the component was last updated.
	UpdatedAt time.Time `json:"updated_at"`

	// Group indicates whether this component is a component group (aka,
	// "parent" or "container") for more specific subcomponents.
	Group bool `json:"group"`

	// OnlyShowIfDegraded indicates whether a component is hidden from view
	// until the status of a parent/container component is in a non-OK or
	// non-operational state.
	OnlyShowIfDegraded bool `json:"only_show_if_degraded"`

	// Showcase indicates whether this component should be showcased.
	Showcase bool `json:"showcase"`

	// Exclude indicates whether this component has been marked for exclusion
	// from overall plugin status evaluation. Until filtering is applied, all
	// components are evaluated for non-operational status.
	Exclude bool `json:"-"`
}

Component represents one of the components defined for a Statuspage-enabled site.

func (Component) IsChild 

func (c Component) IsChild() bool

IsChild indicates whether this component is a member (aka, "child" or "subcomponent") of a component group.

func (Component) IsOKState 

func (c Component) IsOKState() bool

IsOKState indicates whether a component is in an OK or "operational" state.

func (Component) IsParent 

func (c Component) IsParent() bool

IsParent indicates whether this component represents a group of components, otherwise known as a component group (aka, "parent" or "container").

func (Component) String 

func (c Component) String() string

String implements the Stringer interface.

type ComponentGroup 

type ComponentGroup struct {
	Parent        *Component
	Subcomponents []*Component
}

ComponentGroup represents the parent or container component and all subcomponents which comprise a component group. This is intended as a "wrapper" around the parent component and associated Subcomponents and contains pointers to each.

func (ComponentGroup) String 

func (cg ComponentGroup) String() string

String implements the Stringer interface.

type ComponentStartDate 

type ComponentStartDate struct {
	time.Time
}

ComponentStartDate represents the start_date field for a component. This value may potentially be null in the input JSON feed.

func (ComponentStartDate) IsSet 

func (csd ComponentStartDate) IsSet() bool

IsSet is a wrapper around the (time.Time).IsZero() method which indicates whether the start_date field of a component is unset or null.

func (*ComponentStartDate) MarshalJSON 

func (csd *ComponentStartDate) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface. This compliments the custom Unmarshaler implementation to handle potentially null component start_date field value.

func (*ComponentStartDate) UnmarshalJSON 

func (csd *ComponentStartDate) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface to handle potentially null component start_date field value.

type Filter 

type Filter struct {
	Group      string
	Components []string
}

Filter provides the criteria used to select a component group or top-level component for monitoring status evaluation. Any component not matched by these values is excluded from evaluation (aka, "ignored").

Filter is a WIP. Need to setup logic that checks component strings for potential IDs, then falls back to Name match attempts. Same for Group.

func (Filter) String 

func (f Filter) String() string

String implements the Stringer interface for a components Filter.

func (Filter) Validate 

func (f Filter) Validate() error

Validate performs basic validation to assert that given filter settings are valid.

type PrepError added in v0.1.8 

type PrepError struct {

	// Step indicates the specific prep task which failed.
	//
	// NOTE: Constants should be used to make comparisons more reliable.
	Task string

	// Message provides additional (brief) context describing why the error
	// occurred.
	//
	// e.g., "error parsing URL" or "error preparing request for URL"
	Message string

	// Source associated with the prep task.
	//
	// e.g., "/tmp/components.json",
	// "https://status.example.com/api/v2/components.json"
	Source string

	// Cause is the underlying error which occurred while performing a task as
	// part of preparing a components set. This error is "bundled" for later
	// evaluation.
	Cause error
}

PrepError represents a class of errors encountered while performing tasks related to preparing a components Set.

func (*PrepError) Error added in v0.1.8 

func (s *PrepError) Error() string

Error provides a human readable explanation for a components Set preparation task failure.

func (*PrepError) Is added in v0.1.8 

func (s *PrepError) Is(target error) bool

Is supports error wrapping by indicating whether a given error matches the specific failed task associated with this error.

func (*PrepError) Unwrap added in v0.1.8 

func (s *PrepError) Unwrap() error

Unwrap supports error wrapping by returning the enclosed error associated with the specific failed task was encountered as part of preparing a components Set.

type Set 

type Set struct {
	Page struct {
		ID        string    `json:"id"`
		Name      string    `json:"name"`
		TimeZone  string    `json:"time_zone"`
		UpdatedAt time.Time `json:"updated_at"`
		URL       string    `json:"url"`
	} `json:"page"`

	// FilterUsed indicates what Filter values were applied to this Set (if
	// any).
	FilterUsed Filter `json:"-"`

	// Top-level collection of components.
	Components []Component `json:"components"`

	// FilterApplied indicates whether the Filter() method has been called
	// with valid Filter values.
	FilterApplied bool `json:"-"`

	// EvalAllComponents indicates whether the user has opted to skip
	// filtering entirely and evaluate all components.
	EvalAllComponents bool `json:"-"`
}

Set represents the collection of components for a Statuspage-enabled site.

Initial version generated via:

wget https://status.box.com/api/v2/components.json json2struct -f components.json

func NewFromFile 

func NewFromFile(filename string, limit int64, allowUnknownFields bool) (*Set, error)

NewFromFile constructs a components Set by reading and decoding JSON data from a fully-qualified path to a JSON file using the specified number of bytes as the read limit. If specified, unknown fields in the JSON file are ignored. An error is returned if there are problems reading the specified file.

func NewFromURL 

func NewFromURL(ctx context.Context, apiURL string, limit int64, allowUnknownFields bool, userAgent string) (*Set, error)

NewFromURL constructs a components Set by reading and decoding JSON data from a specified URL using the specified number of bytes as the read limit. If specified, unknown fields in the JSON file are ignored. An error is returned if there are problems reading and decoding JSON data. If provided, a custom user agent is supplied in place of the default Go user agent.

func (*Set) AllIDsInListExcluded 

func (cs *Set) AllIDsInListExcluded(componentIDs []string) bool

AllIDsInListExcluded asserts that all component IDs in a given list have been excluded from the components set. This method does not distinguish between top-level, sub or group component values.

func (*Set) AreOnlyIDsInListExcluded 

func (cs *Set) AreOnlyIDsInListExcluded(componentIDs []string) bool

AreOnlyIDsInListExcluded asserts that all component IDs in a given list have been excluded from the components set and vice versa, that all excluded components are in the given list.

This method does not distinguish between top-level, sub or group component values.

func (*Set) ExcludedComponents 

func (cs *Set) ExcludedComponents() []*Component

ExcludedComponents returns any components in the set which have been marked as excluded. The returned collection of component values may be empty. This method does not distinguish between top-level, sub or group component values; any component marked for exclusion is returned.

func (*Set) Filter 

func (cs *Set) Filter(filter Filter) error

Filter applies a given component group and components list Filter against the set, marking any non-matching components as excluded. This allows us to retain the collection as a whole for later review, but focus on the specific components that were requested. The given Filter allows specifying a component group by one of case-insensitive name or ID value. The Filter allows specifying a list of components by a mix of name or ID values.

Specifying a component group by ID results in a single group match. Specifying a component group by name may result in one or many matches.

If specified together, components are required to be subcomponents of at least one of the matched component groups.

If a component group was specified in the Filter, but no components, all subcomponents for each matched component group are exempt from exclusion.

If a component group was specified as a component using its ID, an error is returned. If a component group was specified as a component using its name and the only match is a component group, an error is returned. If a component group is specified as a component by name and there is at least one component match, the component group match is ignored.

NOTE: During filtering, component groups are marked as excluded due to their not being explicitly recorded as "matched". This is not readily apparent in emitted feedback and is an internal detail, though this is pertinent to testing the filtering behavior/logic of the Set.

func (*Set) GetAllGroups 

func (cs *Set) GetAllGroups() ([]ComponentGroup, error)

GetAllGroups returns all component Group values in the set along with their subcomponents as a collection of ComponentGroup values. An error is returned if one is encountered while compiling the collection.

func (*Set) GetComponentByID 

func (cs *Set) GetComponentByID(id string) (*Component, error)

GetComponentByID uses the (case-insensitive) specified component ID as the search key, returning the matching component from the set or an error if a match was not found.

func (*Set) GetComponentsByName 

func (cs *Set) GetComponentsByName(searchKey string) ([]*Component, error)

GetComponentsByName uses the (case-insensitive) specified component name as the key, returning a collection of matching components from the set or an error if a match was not found. If present, multiple components of the same name (even at the same group level) may be returned.

Reminder: component names are not unique, even at the same level.

Component Group names may be duplicated. Subcomponent names may be duplicated (even for the same parent). Component names may be duplicated (even at the top-level).

func (*Set) GetGroupByID 

func (cs *Set) GetGroupByID(id string) (ComponentGroup, error)

GetGroupByID uses the (case-insensitive) specified component ID as the search key, returning a ComponentGroup consisting of a component serving as the component group and its subcomponents from the set or an error if a match was not found.

func (*Set) GetGroupsByName 

func (cs *Set) GetGroupsByName(key string) ([]ComponentGroup, error)

GetGroupsByName uses the (case-insensitive) specified component name as the key, returning a collection of ComponentGroup values for each match or an error if a match was not found in the set. If present, multiple ComponentGroup values may be returned for the same name (even at the same group level).

Reminder: component names are not unique, even at the same level.

component group names may be duplicated. Empty component groups are disallowed by the Statuspage API. Subcomponent names may be duplicated (even for the same parent). Component names may be duplicated (even at the top-level).

func (*Set) Groups 

func (cs *Set) Groups() []*Component

Groups returns any available component Groups in the set as a collection of component values. The returned collection of component values may be empty and does not include subcomponents.

func (*Set) HasCriticalState 

func (cs *Set) HasCriticalState(evalExcluded bool) bool

HasCriticalState indicates whether components in the collection have a specific non-operational status which maps to an CRITICAL state. component Groups are not included since groups mirror the status of subcomponents.

A boolean value is accepted which indicates whether component values marked for exclusion (during filtering) should also be considered. The caller is responsible for filtering the collection prior to calling this method.

func (*Set) HasUnknownState 

func (cs *Set) HasUnknownState(evalExcluded bool) bool

HasUnknownState indicates whether components in the collection have a specific non-operational status which maps to an UNKNOWN state. component Groups are not included since groups mirror the status of subcomponents.

A boolean value is accepted which indicates whether component values marked for exclusion (during filtering) should also be considered. The caller is responsible for filtering the collection prior to calling this method.

func (*Set) HasWarningState 

func (cs *Set) HasWarningState(evalExcluded bool) bool

HasWarningState indicates whether components in the collection have a specific non-operational status which maps to an WARNING state. component Groups are not included since groups mirror the status of subcomponents.

A boolean value is accepted which indicates whether component values marked for exclusion (during filtering) should also be considered. The caller is responsible for filtering the collection prior to calling this method.

func (*Set) IsOKState 

func (cs *Set) IsOKState(evalExcluded bool) bool

IsOKState indicates whether all components in the collection have an operational status which maps to an OK state. component Groups are not included since groups mirror the status of subcomponents.

A boolean value is accepted which indicates whether component values marked for exclusion (during filtering) should also be considered. The caller is responsible for filtering the collection prior to calling this method.

func (*Set) NotExcludedComponents 

func (cs *Set) NotExcludedComponents() []*Component

NotExcludedComponents returns any components in the set which have not been marked as excluded. The returned collection of component values may be empty. This method does not distinguish between top-level, sub or group component values; any component not marked for exclusion is returned.

func (*Set) NumComponents 

func (cs *Set) NumComponents() int

NumComponents returns the count of ALL components in the set (including those marked for exclusion). component Groups are also included in the count.

Subtract component groups from the returned value in order to obtain a count of standalone components and subcomponents. Subtract component groups and subcomponents from the returned value in order to obtain a count of standalone components.

As an alternative to manually calculating independent values, other methods are available which provide them:

  • standalone or "top-level" components
  • subcomponents
  • component Groups

func (*Set) NumCriticalState 

func (cs *Set) NumCriticalState(evalExcluded bool) int

NumCriticalState indicates how many components in the collection have a specific non-operational status which maps to a CRITICAL state. component Groups are not included in the count since groups mirror the status of subcomponents.

A boolean value is accepted which indicates whether all component values are evaluated or only those not marked for exclusion. The caller is responsible for filtering the collection prior to calling this method.

func (*Set) NumExcluded 

func (cs *Set) NumExcluded() int

NumExcluded returns the number of components from the set that have been excluded from evaluation. This includes both operational ("OK") components as well as non-operational components. component Groups are not included in the count (though excluded components within a component group *are* counted).

func (*Set) NumGroups 

func (cs *Set) NumGroups() int

NumGroups returns the count of available component Groups in the set.

func (*Set) NumOKState 

func (cs *Set) NumOKState(evalExcluded bool) int

NumOKState indicates how many components in the collection have an operational status which maps to an OK state. component Groups are not included in the count since groups mirror the status of subcomponents.

A boolean value is accepted which indicates whether component values marked for exclusion (during filtering) should also be considered. The caller is responsible for filtering the collection prior to calling this method.

func (*Set) NumProblemComponents 

func (cs *Set) NumProblemComponents(evalExcluded bool) int

NumProblemComponents returns the count of components in the set which are in a non-OK or non-operational status. component Groups are not included in the count since groups mirror the status of subcomponents.

A boolean value is accepted which indicates whether component values marked for exclusion (during filtering) should also be considered. The caller is responsible for filtering the collection prior to calling this method.

func (*Set) NumProblemGroups 

func (cs *Set) NumProblemGroups() int

NumProblemGroups returns the count of component groups in the set which are in a non-OK or non-operational status. component groups mirror the status of subcomponents.

func (*Set) NumSubcomponents 

func (cs *Set) NumSubcomponents() int

NumSubcomponents returns the count of available Subcomponents in the set. Components marked for exclusion are included.

func (*Set) NumTopLevel 

func (cs *Set) NumTopLevel() int

NumTopLevel returns the count of the standalone, top-level components in the set which are not members or subcomponents of a component Group (aka, a component "container"). Components marked for exclusion are included.

func (*Set) NumUnknownState 

func (cs *Set) NumUnknownState(evalExcluded bool) int

NumUnknownState indicates how many components in the collection have a specific non-operational status which maps to an UNKNOWN state. component Groups are not included in the count since groups mirror the status of subcomponents.

A boolean value is accepted which indicates whether all component values are evaluated or only those not marked for exclusion. The caller is responsible for filtering the collection prior to calling this method.

func (*Set) NumWarningState 

func (cs *Set) NumWarningState(evalExcluded bool) int

NumWarningState indicates how many components in the collection have a specific non-operational status which maps to a WARNING state. component Groups are not included in the count since groups mirror the status of subcomponents.

A boolean value is accepted which indicates whether all component values are evaluated or only those not marked for exclusion. The caller is responsible for filtering the collection prior to calling this method.

func (*Set) ProblemComponentGroups 

func (cs *Set) ProblemComponentGroups() ([]ComponentGroup, error)

ProblemComponentGroups returns ComponentGroup values from the set composed only of component group and subcomponent values which are in a non-OK or non-operational status.

The returned collection of ComponentGroup values may be empty. An error is returned if there are problems compiling the collection of ComponentGroup values.

func (*Set) ProblemComponents 

func (cs *Set) ProblemComponents(evalExcluded bool) []*Component

ProblemComponents returns any subcomponents in the set in a non-OK or non-operational status as a collection of component values. The returned collection of component values may be empty. component groups are not included in the count since groups mirror the status of subcomponents.

A boolean value is accepted which indicates whether component values marked for exclusion (during filtering) should also be considered. The caller is responsible for filtering the collection prior to calling this method.

func (*Set) ServiceState 

func (cs *Set) ServiceState(evalExcluded bool) nagios.ServiceState

ServiceState returns the current Nagios ServiceState for the Set. A boolean value is accepted which indicates whether component values marked for exclusion (during filtering) should also be considered. The caller is responsible for filtering the collection prior to calling this method.

func (*Set) Subcomponents 

func (cs *Set) Subcomponents() []*Component

Subcomponents returns any available subcomponents in the set as a collection of component values. Components marked for exclusion are included. The returned collection of component values may be empty.

func (*Set) TopLevel 

func (cs *Set) TopLevel() []*Component

TopLevel returns the standalone, top-level components which are not members or subcomponents of a component group (aka, a component "container"). Components marked for exclusion are included.

func (*Set) Validate 

func (cs *Set) Validate() error

Validate runs very basic validation checks on the decoded JSON input for fields that we either use or expect to use in the future. An error is returned if any validation checks fail.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.