control

package
v1.19.3 Latest Latest
Warning

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

 Go to latest Published: Feb 11, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package control provides control modes for mandatory component validation.

This package defines different validation modes that can be applied to mandatory components in a status monitoring system. These modes determine how strictly components must be validated.

Available Modes

The package defines five control modes:

  • Ignore: No validation required (default)
  • Should: Component should be present but is not mandatory
  • Must: Component must be present and healthy
  • AnyOf: At least one of the components must be healthy
  • Quorum: A majority of components must be healthy

Usage Example 

import "github.com/nabbar/golib/status/control"

// Parse a mode from string
mode := control.Parse("must")
fmt.Println(mode.String()) // Output: Must

// Use in configuration
if mode == control.Must {
    // Enforce strict validation
}

Serialization

The Mode type supports multiple serialization formats:

  • JSON: Marshals to/from string representation
  • YAML: Marshals to/from string representation
  • TOML: Marshals to/from string representation
  • Text: Marshals to/from string representation
  • CBOR: Marshals to/from string representation

All parsing is case-insensitive for convenience.

Integration

This package is designed to work with:

  • github.com/nabbar/golib/status/mandatory: For managing mandatory components
  • github.com/nabbar/golib/status: For overall status management

See also: github.com/nabbar/golib/status/mandatory for usage with mandatory components.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ViperDecoderHook 

func ViperDecoderHook() libmap.DecodeHookFuncType

ViperDecoderHook returns a mapstructure decode hook for Viper configuration.

This hook allows Mode values to be automatically decoded from configuration files (YAML, JSON, TOML, etc.) when using Viper. The hook converts string values to Mode types during configuration unmarshaling.

The decoding is case-insensitive and supports all Mode string representations.

Usage with Viper: 

import (
    "github.com/spf13/viper"
    "github.com/nabbar/golib/status/control"
)

v := viper.New()
v.SetConfigType("yaml")

// Register the decode hook
decoderConfig := &mapstructure.DecoderConfig{
    DecodeHook: control.ViperDecoderHook(),
    Result:     &config,
}

Configuration file example (YAML): 

mandatory:
  mode: must
  keys:
    - database
    - cache

The "must" string will be automatically decoded to control.Must.

See also: github.com/spf13/viper for Viper configuration management.

Types

type Mode 

type Mode uint8

Mode represents a control mode for mandatory component validation.

Mode determines how strictly components must be validated in a status monitoring system. It is implemented as a uint8 for efficient storage and comparison.

The zero value (Ignore) means no validation is required. 

const (
	// Ignore indicates no validation is required for the component.
	// This is the default mode and allows components to be absent or unhealthy
	// without affecting the overall status.
	Ignore Mode = iota

	// Should indicates the component should be present but is not mandatory.
	// If the component is absent or unhealthy, it may generate a warning
	// but will not cause a failure.
	Should

	// Must indicates the component must be present and healthy.
	// If the component is absent or unhealthy, the overall status will fail.
	Must

	// AnyOf indicates at least one of the components in the group must be healthy.
	// This mode is useful for redundant components where any one can satisfy
	// the requirement.
	AnyOf

	// Quorum indicates a majority of components in the group must be healthy.
	// This mode is useful for distributed systems where a quorum is required
	// for proper operation.
	Quorum
)

func Parse 

func Parse(s string) Mode

Parse converts a string to a Mode.

The parsing is case-insensitive and supports the following values:

  • "should" -> Should
  • "must" -> Must
  • "anyof" -> AnyOf
  • "quorum" -> Quorum
  • any other value -> Ignore

Example: 

mode := control.Parse("MUST")
fmt.Println(mode) // Output: Must

mode = control.Parse("invalid")
fmt.Println(mode) // Output: (empty string for Ignore)

func ParseBytes 

func ParseBytes(p []byte) Mode

ParseBytes converts a byte slice to a Mode.

This is a convenience wrapper around Parse that converts the byte slice to a string before parsing. The parsing is case-insensitive.

Example: 

mode := control.ParseBytes([]byte("must"))
fmt.Println(mode) // Output: Must

func ParseInt64 

func ParseInt64(p int64) Mode

ParseInt64 converts an int64 to a Mode.

This function is useful when reading Mode values from signed numeric configuration or database fields. Negative values are treated as 0 (Ignore).

Values are mapped as follows:

  • 0 or negative -> Ignore
  • 1 -> Should
  • 2 -> Must
  • 3 -> AnyOf
  • 4 -> Quorum
  • any other value -> Ignore

Example: 

mode := control.ParseInt64(2)
fmt.Println(mode) // Output: Must

mode = control.ParseInt64(-1)
fmt.Println(mode) // Output: (empty string for Ignore)

func ParseUint64 added in v1.19.0 

func ParseUint64(p uint64) Mode

ParseUint64 converts a uint64 to a Mode.

This function is useful when reading Mode values from numeric configuration or database fields. Values are mapped as follows:

  • 0 -> Ignore
  • 1 -> Should
  • 2 -> Must
  • 3 -> AnyOf
  • 4 -> Quorum
  • any other value -> Ignore

Values larger than math.MaxUint8 are clamped to MaxUint8 before conversion.

Example: 

mode := control.ParseUint64(2)
fmt.Println(mode) // Output: Must

mode = control.ParseUint64(999)
fmt.Println(mode) // Output: (empty string for Ignore)

func (Mode) Code 

func (c Mode) Code() string

Code returns the lowercase code representation of the Mode.

This is a convenience method that returns the lowercase version of String(). It's useful for case-insensitive comparisons and configuration files.

Returns:

  • Should -> "should"
  • Must -> "must"
  • AnyOf -> "anyof"
  • Quorum -> "quorum"
  • Ignore -> "" (empty string)

Example: 

mode := control.Must
fmt.Println(mode.Code()) // Output: must

func (Mode) MarshalCBOR 

func (c Mode) MarshalCBOR() ([]byte, error)

MarshalCBOR implements cbor.Marshaler interface.

The Mode is marshaled as a CBOR string using its String() representation. CBOR (Concise Binary Object Representation) is a binary data serialization format based on JSON.

Example: 

mode := control.Must
data, _ := mode.MarshalCBOR()
// data contains CBOR-encoded "Must"

See also: github.com/fxamacker/cbor for CBOR encoding/decoding.

func (Mode) MarshalJSON 

func (c Mode) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface.

The Mode is marshaled as a JSON string using its String() representation.

Example: 

mode := control.Must
data, _ := json.Marshal(mode)
fmt.Println(string(data)) // Output: "Must"

func (Mode) MarshalTOML 

func (c Mode) MarshalTOML() ([]byte, error)

MarshalTOML implements toml.Marshaler interface.

The Mode is marshaled as a TOML string using its JSON representation.

Example: 

mode := control.Must
data, _ := mode.MarshalTOML()
fmt.Println(string(data)) // Output: "Must"

func (Mode) MarshalText 

func (c Mode) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler interface.

The Mode is marshaled as plain text using its String() representation. This is useful for text-based protocols and formats.

Example: 

mode := control.Must
data, _ := mode.MarshalText()
fmt.Println(string(data)) // Output: Must

func (Mode) MarshalYAML 

func (c Mode) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler interface.

The Mode is marshaled as a YAML string using its String() representation.

Example: 

mode := control.Must
data, _ := yaml.Marshal(mode)
fmt.Println(string(data)) // Output: Must

func (Mode) String 

func (c Mode) String() string

String returns the string representation of the Mode.

The string representation uses PascalCase for readability:

  • Should -> "Should"
  • Must -> "Must"
  • AnyOf -> "AnyOf"
  • Quorum -> "Quorum"
  • Ignore -> "" (empty string)

This method is used by the fmt package when printing Mode values.

Example: 

mode := control.Must
fmt.Println(mode.String()) // Output: Must

func (*Mode) UnmarshalCBOR 

func (c *Mode) UnmarshalCBOR(bytes []byte) error

UnmarshalCBOR implements cbor.Unmarshaler interface.

The Mode is unmarshaled from CBOR-encoded data. The parsing is case-insensitive. If the CBOR value is not a valid Mode string, it defaults to Ignore.

Example: 

var mode control.Mode
cborData, _ := cbor.Marshal("must")
mode.UnmarshalCBOR(cborData)
fmt.Println(mode) // Output: Must

See also: github.com/fxamacker/cbor for CBOR encoding/decoding.

func (*Mode) UnmarshalJSON 

func (c *Mode) UnmarshalJSON(bytes []byte) error

UnmarshalJSON implements json.Unmarshaler interface.

The Mode is unmarshaled from a JSON string. The parsing is case-insensitive. If the JSON value is not a valid Mode string, it defaults to Ignore.

Example: 

var mode control.Mode
json.Unmarshal([]byte(`"must"`), &mode)
fmt.Println(mode) // Output: Must

func (*Mode) UnmarshalTOML 

func (c *Mode) UnmarshalTOML(i interface{}) error

UnmarshalTOML implements toml.Unmarshaler interface.

The Mode is unmarshaled from a TOML value which can be either a byte slice or a string. The parsing is case-insensitive. If the value is not a valid Mode string or type, it returns an error.

Example: 

var mode control.Mode
mode.UnmarshalTOML("must")
fmt.Println(mode) // Output: Must

func (*Mode) UnmarshalText 

func (c *Mode) UnmarshalText(bytes []byte) error

UnmarshalText implements encoding.TextUnmarshaler interface.

The Mode is unmarshaled from plain text. The parsing is case-insensitive. If the text is not a valid Mode string, it defaults to Ignore.

Example: 

var mode control.Mode
mode.UnmarshalText([]byte("must"))
fmt.Println(mode) // Output: Must

func (*Mode) UnmarshalYAML 

func (c *Mode) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler interface.

The Mode is unmarshaled from a YAML string. The parsing is case-insensitive. If the YAML value is not a valid Mode string, it defaults to Ignore.

Example: 

var mode control.Mode
yaml.Unmarshal([]byte("must"), &mode)
fmt.Println(mode) // Output: Must

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.