go_goutils/logging/types.go

package logging

import (
	"log"
	"os"

	`r00t2.io/goutils/bitmask`
)

type logPrio bitmask.MaskBit

/*
Logger is one of the various loggers offered by this module.
*/
type Logger interface {
	Alert(s string, v ...interface{}) (err error)
	Crit(s string, v ...interface{}) (err error)
	Debug(s string, v ...interface{}) (err error)
	Emerg(s string, v ...interface{}) (err error)
	Err(s string, v ...interface{}) (err error)
	Info(s string, v ...interface{}) (err error)
	Notice(s string, v ...interface{}) (err error)
	Warning(s string, v ...interface{}) (err error)
	DoDebug(d bool) (err error)
	GetDebug() (d bool)
	SetPrefix(p string) (err error)
	GetPrefix() (p string, err error)
	Setup() (err error)
	Shutdown() (err error)
	ToLogger(prio logPrio) (stdLibLog *log.Logger)
}

/*
StdLogger uses the log package in stdlib to perform all logging. The default is to write to STDOUT.
If you wish to modify the underling log.Logger object, you can access it directly via StdLogger.Logger.
*/
type StdLogger struct {
	// All log.Logger fields/methods are exposed.
	*log.Logger
	/*
		EnableDebug indicates if the debug filter should be disabled (true) or if the filter should be enabled (false).
		This prevents potential data leak of sensitive information, as some loggers (e.g. FileLogger) will otherwise write all messages.
	*/
	EnableDebug bool
	// Prefix indicates the prefix for log entries; in shared logs, this helps differentiate the source.
	Prefix string
	/*
		LogFlags control some of the formatting options presented as an OR'd value.
		See https://pkg.go.dev/log#pkg-constants for flag details.
		e.g.:
			*StdLogger.LogFlags = log.Ldate | log.Lmicroseconds | log.Llongfile | log.LUTC // a very detailed log output
			*StdLogger.LogFlags = log.Ldate | log.Ltime // the flags used by log.Default() (also available as simply log.LstdFlags)
		The default is 0; no flags (no output except prefix if non-empty and message).
		You will need to run *StdLogger.Shutdown and then *StdLogger.Setup again if you wish to change this.
	*/
	LogFlags int
	/*
		EnableStdOut is true if the log will send to STDOUT.
		If false (default), no output will be written to STDOUT.
		You will need to run StdLogger.Shutdown and then StdLogger.Setup again if you wish to change this.

		If EnableStdOut is false and EnableStdErr is false, no logging output will occur by default
		and StdLogger.Logger will be largely useless.
		It will be up to you to modify the underlying log.Logger to behave as you want.
	*/
	EnableStdOut bool
	/*
		EnableStdErr is true if the log will send to STDERR.
		If false (default), no output will be written to STDERR.
		You will need to run StdLogger.Shutdown and then StdLogger.Setup again if you wish to change this.

		If EnableStdErr is false and EnableStdOut is false, no logging output will occur by default
		and StdLogger.Logger will be largely useless.
		It will be up to you to modify the underlying log.Logger to behave as you want.
	*/
	EnableStdErr bool
}

/*
FileLogger uses a StdLogger with a file handle writer to write to the file given at Path.

NOTE: If you wish to change the FileLogger.StdLogger.LogFlags, do *not* run FileLogger.StdLogger.Setup after doing so as this
will instead create a logger detached from the file handler. Instead, be sure to call FileLogger.Setup.
(Alternatively, run FileLogger.Shutdown and replace your logger with a new FileLogger.)
*/
type FileLogger struct {
	// StdLogger is used for the log formation and handling. See StdLogger for more details.
	StdLogger
	// Path is the path to the logfile.
	Path string
	// writer is used for the writing out of the log file.
	writer *os.File
}

// NullLogger is used mainly for test implementations, mockup code, etc. It does absolutely nothing with all messages sent to it.
type NullLogger struct{}

// MultiLogger is used to contain one or more Loggers and present them all as a single Logger.
type MultiLogger struct {
	/*
		EnableDebug indicates if the debug filter should be disabled (true) or if the filter should be enabled (false).
		This prevents potential data leak of sensitive information, as some loggers (e.g. FileLogger) will otherwise write all messages.
	*/
	EnableDebug bool
	// Prefix indicates the prefix for log entries; in shared logs, this helps differentiate the source.
	Prefix string
	/*
		Loggers contains a map of map[logname]Logger. It can be used to set log-specific options, or replace a Logger
		with one of a different type or options.
	*/
	Loggers map[string]Logger
}

// logWriter is used as a log.Logger and is returned by <Logger>.ToLogger.
type logWriter struct {
	backend Logger
	prio    logPrio
}

// nullWriter is used as a shortcut by NullLogger.ToLogger.
type nullWriter struct{}