Documentation
¶
Overview ¶
Package control provides the validation modes that govern how component health affects the overall application status. These modes are used to define flexible and robust health check policies.
The package defines a set of standard control modes (Ignore, Should, Must, AnyOf, Quorum) and provides utilities for parsing and serializing them.
Index ¶
- func ViperDecoderHook() libmap.DecodeHookFuncType
- type Mode
- func (c Mode) Code() string
- func (c Mode) MarshalCBOR() ([]byte, error)
- func (c Mode) MarshalJSON() ([]byte, error)
- func (c Mode) MarshalTOML() ([]byte, error)
- func (c Mode) MarshalText() ([]byte, error)
- func (c Mode) MarshalYAML() (interface{}, error)
- func (c Mode) String() string
- func (c *Mode) UnmarshalCBOR(bytes []byte) error
- func (c *Mode) UnmarshalJSON(bytes []byte) error
- func (c *Mode) UnmarshalTOML(i interface{}) error
- func (c *Mode) UnmarshalText(bytes []byte) error
- func (c *Mode) UnmarshalYAML(value *yaml.Node) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ViperDecoderHook ¶
func ViperDecoderHook() libmap.DecodeHookFuncType
ViperDecoderHook returns a `mapstructure.DecodeHookFunc` that can be used with Viper to automatically decode string values from configuration files (e.g., YAML, JSON, TOML) into `Mode` types during the unmarshaling process.
This hook is essential for a seamless configuration experience, as it allows developers to use human-readable strings (like "must" or "Should") in their config files, which are then automatically converted to the correct `Mode` type. The decoding is case-insensitive.
Example usage with Viper:
import (
"github.com/spf13/viper"
"github.com/mitchellh/mapstructure"
"github.com/nabbar/golib/status/control"
)
type MyConfig struct {
ValidationMode control.Mode `mapstructure:"validation_mode"`
}
v := viper.New()
// ... load config from file or other source ...
var cfg MyConfig
// The hook is passed to Viper's Unmarshal function.
err := v.Unmarshal(&cfg, viper.DecodeHook(control.ViperDecoderHook()))
In a YAML file:
validation_mode: "Must"
The string "Must" will be correctly decoded into `control.Must`.
Types ¶
type Mode ¶
type Mode uint8
Mode represents a control mode for mandatory component validation. It determines the strictness of the health check for a component or a group of components. It is implemented as a `uint8` for efficiency.
const ( // Ignore indicates that no validation is required for the component. // This is the default mode (zero value). Components in this mode are // monitored, but their status (even if KO) does not affect the overall // application status. Ignore Mode = iota // Should indicates that the component is important but not critical. If the // component is unhealthy (KO or WARN), it will generate a warning but will // not cause a critical failure (KO) of the overall application. This is // useful for optional features or degraded modes. Should // Must indicates that the component is critical and must be healthy. If the // component is unhealthy (KO), the overall application status will be marked // as failed (KO). If it is WARN, the overall status will be WARN. Must // AnyOf is used for redundant groups of components (e.g., a cluster of // read-only databases). It requires at least one component in the group to // be healthy (OK or WARN). If all components are KO, the group is KO. AnyOf // Quorum is used for distributed systems requiring consensus. It requires a // majority (>50%) of the components in the group to be healthy (OK or WARN). // If 50% or fewer are healthy, the group is considered KO. Quorum )
func Parse ¶
Parse converts a string to a `Mode`. The parsing is case-insensitive. If the string does not match any known mode, `Ignore` is returned as the default.
Supported values:
- "ignore" -> Ignore
- "should" -> Should
- "must" -> Must
- "anyof" -> AnyOf
- "quorum" -> Quorum
func ParseBytes ¶
ParseBytes is a convenience wrapper for `Parse` that accepts a byte slice. It converts the byte slice to a string and calls `Parse`.
func ParseInt64 ¶
ParseInt64 converts an `int64` to a `Mode`. Negative values are treated as 0 (`Ignore`). This is useful for signed numeric configurations.
Mapping:
- < 0 -> Ignore
- 0 -> Ignore
- 1 -> Should
- 2 -> Must
- 3 -> AnyOf
- 4 -> Quorum
func ParseUint64 ¶ added in v1.19.0
ParseUint64 converts a `uint64` to a `Mode`. This is useful when reading mode values from numeric configurations or databases. If the value is out of the valid range for `Mode`, `Ignore` is returned.
Mapping:
- 0 -> Ignore
- 1 -> Should
- 2 -> Must
- 3 -> AnyOf
- 4 -> Quorum
func (Mode) Code ¶
Code returns the lowercase string representation of the `Mode`. This is primarily used for case-insensitive comparisons and for storing the mode in configuration files in a consistent format.
Example:
fmt.Println(control.Must.Code()) // Output: must
func (Mode) MarshalCBOR ¶
MarshalCBOR implements the `cbor.Marshaler` interface. It serializes the `Mode` into a CBOR (Concise Binary Object Representation) string. CBOR is a binary data serialization format loosely based on JSON.
func (Mode) MarshalJSON ¶
MarshalJSON implements the `json.Marshaler` interface. It serializes the `Mode` into a JSON string using its PascalCase representation (e.g., "Must", "Should").
Example:
data, _ := json.Marshal(control.Must) // data is []byte(`"Must"`)
func (Mode) MarshalTOML ¶
MarshalTOML implements the `toml.Marshaler` interface. It serializes the `Mode` into a TOML string. It reuses `MarshalJSON` internally to ensure consistency.
func (Mode) MarshalText ¶
MarshalText implements the `encoding.TextMarshaler` interface. It serializes the `Mode` into a plain text byte slice using its PascalCase representation. This is useful for generic text-based protocols or logging.
func (Mode) MarshalYAML ¶
MarshalYAML implements the `yaml.Marshaler` interface. It serializes the `Mode` into a YAML string using its PascalCase representation.
func (Mode) String ¶
String returns the PascalCase string representation of the `Mode`. The `Ignore` mode returns an empty string, which is its defined string value.
This method implements the `fmt.Stringer` interface, allowing `Mode` values to be printed directly and clearly in logs and other outputs.
Example:
fmt.Println(control.Must) // Output: Must
func (*Mode) UnmarshalCBOR ¶
UnmarshalCBOR implements the `cbor.Unmarshaler` interface. It deserializes a CBOR-encoded byte slice into a `Mode`. The parsing is case-insensitive.
func (*Mode) UnmarshalJSON ¶
UnmarshalJSON implements the `json.Unmarshaler` interface. It deserializes a JSON string into a `Mode`. The parsing is case-insensitive. If the JSON value is not a valid string or does not match a known mode, it defaults to `Ignore`.
Example:
var m control.Mode json.Unmarshal([]byte(`"must"`), &m) // m is control.Must
func (*Mode) UnmarshalTOML ¶
UnmarshalTOML implements the `toml.Unmarshaler` interface. It deserializes a TOML value into a `Mode`. It supports both byte slices and strings as input. The parsing is case-insensitive.
If the input is not a byte slice or a string, it returns an error indicating an invalid format.
func (*Mode) UnmarshalText ¶
UnmarshalText implements the `encoding.TextUnmarshaler` interface. It deserializes a plain text byte slice into a `Mode`. The parsing is case-insensitive.
Source Files