config

package
v0.8.5 Latest Latest
Warning

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

 Go to latest Published: Nov 15, 2023 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package config provides types and functions to collect, validate and apply user-provided settings.

Index

Constants

View Source 
const (
	HelpFlagLong  string = "help"
	HelpFlagShort string = "h"
)

Flag names. Exported so that they can be referenced from tests.

View Source 
const (

	// AuthTypeBasic indicates Basic Authentication (username/password).
	AuthTypeBasic string = "basic"

	// AuthTypeOAuth2ClientCreds indicates OAuth2 Client Credentials flow.
	AuthTypeOAuth2ClientCreds string = "oauth2"
)

Supported authentication types used by applications in this project.

These are also the only valid values for the auth_type INI config file key.

View Source 
const (

	// LogLevelDisabled maps to zerolog.Disabled logging level
	LogLevelDisabled string = "disabled"

	// LogLevelPanic maps to zerolog.PanicLevel logging level
	LogLevelPanic string = "panic"

	// LogLevelFatal maps to zerolog.FatalLevel logging level
	LogLevelFatal string = "fatal"

	// LogLevelError maps to zerolog.ErrorLevel logging level
	LogLevelError string = "error"

	// LogLevelWarn maps to zerolog.WarnLevel logging level
	LogLevelWarn string = "warn"

	// LogLevelInfo maps to zerolog.InfoLevel logging level
	LogLevelInfo string = "info"

	// LogLevelDebug maps to zerolog.DebugLevel logging level
	LogLevelDebug string = "debug"

	// LogLevelTrace maps to zerolog.TraceLevel logging level
	LogLevelTrace string = "trace"
)

Variables

View Source 
var (
	// ErrVersionRequested indicates that the user requested application
	// version information
	ErrVersionRequested = errors.New("version information requested")

	// ErrHelpRequested indicates that the user requested application
	// help/usage information.
	ErrHelpRequested = errors.New("help/usage information requested")

	// ErrAppTypeNotSpecified indicates that a tool in this project failed to
	// specify a valid application type.
	ErrAppTypeNotSpecified = errors.New("valid app type not specified")

	// ErrInvalidAuthType indicates that an invalid or unsupported
	// authentication type was specified.
	ErrInvalidAuthType = errors.New("invalid auth type")

	// ErrConfigNotInitialized indicates that the configuration is not in a
	// usable state and application execution can not successfully proceed.
	ErrConfigNotInitialized = errors.New("configuration not initialized")
)

Functions

func Branding 

func Branding(msg string) func() string

Branding accepts a message and returns a function that concatenates that message with version information. This function is intended to be called as a final step before application exit after any other output has already been emitted.

func Usage 

func Usage(flagSet *flag.FlagSet, w io.Writer) func()

Usage is a custom override for the default Help text provided by the flag package. Here we prepend some additional metadata to the existing output.

func Version 

func Version() string

Version emits application name, version and repo location.

Types

type AppType added in v0.4.21 

type AppType struct {

	// PluginIMAPMailboxBasicAuth represents an application used as a
	// monitoring plugin for evaluating IMAP mailboxes.
	//
	// Basic Authentication is used to login.
	PluginIMAPMailboxBasicAuth bool

	// PluginIMAPMailboxOAuth2 represents an application used as a monitoring
	// plugin for evaluating IMAP mailboxes.
	//
	// An OAuth2 flow is used to login.
	PluginIMAPMailboxOAuth2 bool

	// FetcherOAuth2TokenFromCache represents an application used to obtain an
	// OAuth2 token via Client Credentials flow from local storage/cache.
	FetcherOAuth2TokenFromCache bool

	// FetcherOAuth2TokenFromAuthServer represents an application used to
	// obtain an OAuth2 token via Client Credentials flow from an
	// authorization server.
	FetcherOAuth2TokenFromAuthServer bool

	// ReporterIMAPMailbox represents an application used for generating
	// reports for specified IMAP mailboxes.
	//
	// Unlike an Inspector application which is focused on testing or
	// gathering specific details for troubleshooting purposes or a monitoring
	// plugin which is intended for providing a severity-based outcome, a
	// Reporter application is intended for gathering information as an
	// overview.
	ReporterIMAPMailbox bool

	// InspectorIMAPCaps represents an application used for one-off or
	// isolated checks of an IMAP server's advertised capabilities.
	//
	// Unlike a monitoring plugin which is focused on specific attributes
	// resulting in a severity-based outcome, an Inspector application is
	// intended for examining a small set of targets for
	// informational/troubleshooting purposes.
	InspectorIMAPCaps bool
}

AppType represents the type of application that is being configured/initialized. Not all application types will use the same features and as a result will not accept the same flags. Unless noted otherwise, each of the application types are incompatible with each other, though some flags are common to all types.

type Config 

type Config struct {

	// EmitBranding controls whether "generated by" text is included at the
	// bottom of application output. This output is included in the Nagios
	// dashboard and notifications. This output may not mix well with branding
	// output from other tools such as atc0005/send2teams which also insert
	// their own branding output.
	EmitBranding bool

	// ShowVersion is a flag indicating whether the user opted to display only
	// the version string and then immediately exit the application.
	ShowVersion bool

	// ShowHelp indicates whether the user opted to display usage information
	// and exit the application.
	ShowHelp bool

	// ConfigFileLoaded is an internal flag indicating whether a user-provided
	// config file was specified *and* loaded, or a config file was
	// automatically detected *and* loaded.
	ConfigFileLoaded bool

	// ConfigFile is the path to the user-provided config file. This config
	// file is not currently used by the check_imap_mailbox plugin provided by
	// this project.
	ConfigFile string

	// ConfigFileUsed is an internal field indicating *what* config file was
	// loaded, be it explicitly specified by the user or automatically
	// detected from a known location.
	ConfigFileUsed string

	// NetworkType indicates whether an attempt should be made to connect to
	// only IPv4, only IPv6 or IMAP servers listening on either of IPv4 or
	// IPv6 addresses ("auto").
	NetworkType string

	// ReportFileOutputDir is the full path to the directory where email
	// summary report files will be generated. Not currently used by the
	// Nagios plugin.
	ReportFileOutputDir string

	// LogFileOutputDir is the full path to the directory where log files will
	// be generated. Not currently used by the Nagios plugin.
	LogFileOutputDir string

	// LogFileHandle is reference to a log file for deferred closure.
	LogFileHandle *os.File

	// LoggingLevel is the supported logging level for this application.
	LoggingLevel string

	// Accounts is the collection of IMAP mail accounts checked by
	// applications provided by this project.
	Accounts []MailAccount

	// FetcherOAuth2TokenSettings is the collection of OAuth2 token "fetcher"
	// settings.
	FetcherOAuth2TokenSettings FetcherOAuth2TokenSettings

	// Log is an embedded zerolog Logger initialized via config.New().
	Log zerolog.Logger
	// contains filtered or unexported fields
}

Config represents the application configuration as specified via command-line flags.

func New 

func New(appType AppType) (*Config, error)

New is a factory function that produces a new Config object based on user provided flag and config file values. It is responsible for validating user-provided values and initializing the logging settings used by this application.

func (Config) AccountNames added in v0.5.0 

func (c Config) AccountNames() []string

AccountNames returns the collection of names associated with accounts. If basic auth is used this will be usernames, if oauth2 is used this will be mailbox names. If an account or mailbox is specified as "user@example.com" only the "user" portion of that value is returned.

func (Config) AccountProcessDelay added in v0.5.0 

func (c Config) AccountProcessDelay() time.Duration

AccountProcessDelay returns the configured delay between processing accounts in a collection.

func (Config) AuthType added in v0.5.0 

func (c Config) AuthType() string

AuthType returns the authentication type from the first account entry in the collection. This value should be the same for all account entries in the collection. For the Plugin app type this is a collection of one entry, for the Reporter app type the same server value is recorded for each account (convenience).

func (*Config) Help added in v0.6.0 

func (c *Config) Help() string

Help emits application usage information to the previously configured destination for usage and error messages.

func (Config) MinTLSVersion added in v0.4.5 

func (c Config) MinTLSVersion() uint16

MinTLSVersion returns the applicable `tls.VersionTLS*` numeric constant corresponding to the user-specified (or default) TLS version string keyword.

func (Config) MinTLSVersionKeyword added in v0.4.5 

func (c Config) MinTLSVersionKeyword() string

MinTLSVersionKeyword returns the user-specified (or default) TLS version string keyword.

func (Config) Port 

func (c Config) Port() int

Port returns the IMAP server port value from the first account entry in the collection. This value should be the same for all account entries in the collection. For the Plugin app type this is a collection of one entry, for the Reporter app type the same server value is recorded for each account (convenience).

func (Config) RetrievalAttempts added in v0.6.0 

func (c Config) RetrievalAttempts() int

RetrievalAttempts returns the configured retrieval attempts or the default value if not specified.

func (Config) Server 

func (c Config) Server() string

Server returns the IMAP server value from the first account entry in the collection. This value should be the same for all account entries in the collection. For the Plugin app type this is a collection of one entry, for the Reporter app type the same server value is recorded for each account (convenience).

func (Config) SupportedAuthTypes added in v0.5.0 

func (c Config) SupportedAuthTypes() []string

SupportedAuthTypes returns the complete list of supported authentication types used by applications in this project.

type FetcherOAuth2TokenSettings added in v0.6.0 

type FetcherOAuth2TokenSettings struct {
	OAuth2ClientCredentialsFlow

	// Filename is the optional filename used to hold a retrieved token.
	Filename string

	// EmitTokenAsJSON indicates whether the retrieved token is saved in
	// the original JSON payload format or as just the access token itself.
	EmitTokenAsJSON bool
}

FetcherOAuth2TokenSettings is the collection of OAuth2 token "fetcher" settings.

type MailAccount added in v0.2.9 

type MailAccount struct {
	// Server is the FQDN associated with the IMAP server.
	//
	// Use of IP Addresses is discouraged; TLS is needed for secure
	// communication with IMAP servers and IP Addresses are rarely listed in
	// Subject Alternate Names (SANs) lists for certificates.
	Server string

	// Port is the TCP port associated with the IMAP server. This is usually
	// 993 but may differ for some installations.
	Port int

	// AuthType is either "basic" for Basic Authentication or "oauth2" for the
	// Client Credentials OAuth2 flow. This value acts as a logic switch for
	// the Reporter application.
	AuthType string

	// Folders is a collection of paths associated with an account. This
	// includes paths such as "Inbox", "Junk EMail" or "Trash".
	Folders multiValueFlag

	// Username is usually the full email address associated with an account.
	Username string

	// Password is the plaintext password for the email account.
	Password string

	// OAuth2Settings is a collection of settings specific to OAuth2
	// authentication with the service hosting the email account.
	OAuth2Settings OAuth2ClientCredentialsFlow

	// Name is often the bare username for the email account, but may not be.
	// This is used as the section header within the configuration file.
	//
	// NOTE: As of the v0.4.x releases this field is used exclusively by the
	// reporter tool.
	Name string
}

MailAccount represents an email account. The values are provided via command-line flags or are specified within a configuration file.

type OAuth2ClientCredentialsFlow added in v0.6.0 

type OAuth2ClientCredentialsFlow struct {
	// ClientID is the client ID used by the application that asks for
	// authorization. It must be unique across all clients that the
	// authorization server handles. This ID represents the registration
	// information provided by the client.
	//
	// The client identifier is not a secret; it is exposed to the resource
	// owner and MUST NOT be used alone for client authentication. The client
	// identifier is unique to the authorization server.
	// https://datatracker.ietf.org/doc/html/rfc6749#section-2.2
	ClientID string

	// ClientSecret is a secret known only to the application and the
	// authorization server. It can be considered the application's own
	// password. This value is provided upon application authorization.
	ClientSecret string

	// Scopes is the collection of permissions or "scopes" requested by an
	// application from the authorization server.
	//
	// Scopes let you specify exactly what type of access the application
	// needs. Scopes limit access for OAuth tokens. They do not grant any
	// additional permission beyond that which the user already has.
	//
	// https://www.oauth.com/oauth2-servers/scope/
	// https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps
	Scopes multiValueFlag

	// SharedMailbox is the email account that is to be accessed by the
	// application using the given client ID, client secret values. This is
	// usually a shared mailbox among a team.
	SharedMailbox string

	// TokenURL is the authority endpoint for token retrieval.
	TokenURL string

	// RetrievalAttempts indicates how many attempts should be made to
	// retrieve a token.
	RetrievalAttempts int
}

OAuth2ClientCredentialsFlow is a collection of OAuth2 settings used to obtain a token via OAuth2 Client Credentials flow.

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.