logger

type Context interface {
	// WriteOut sends the log message with the collected data from all the
	// Append... methods
	WriteOut(level Level, message string)

	// SetCaller sets the caller and its line value for this context.
	//
	// Calling this method multiple times shall override the previous value.
	// An empty string on the file name signifies to unset this field.
	//
	// In contrast to AppendString, the logging sink is allowed to render this
	// differently. E.g. some may render it as yet another fields named "caller"
	// and "line", others may render it as a specific HTTP header in a request.
	SetCaller(file string, line int) Context
	// SetError sets the error value for this context.
	//
	// Calling this method multiple times shall override the previous value.
	// An nil signifies to unset this field.
	//
	// In contrast to AppendString, the logging sink is allowed to render this
	// differently. E.g. some may render it as yet another field named "error",
	// others may render it as a specific HTTP header in a request.
	SetError(value error) Context
	// AppendString adds a string value for a specific key to this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendString(key string, value string) Context
	// AppendRune adds a rune value for a specific key to this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendRune(key string, value rune) Context
	// AppendBool adds a boolean value for a specific key to this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendBool(key string, value bool) Context
	// AppendInt adds an integer value for a specific key to this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendInt(key string, value int) Context
	// AppendInt32 adds an integer value for a specific key to this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendInt32(key string, value int32) Context
	// AppendInt64 adds an integer value for a specific key to this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendInt64(key string, value int64) Context
	// AppendUint adds an integer value for a specific key to this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendUint(key string, value uint) Context
	// AppendUint32 adds an integer value for a specific key to this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendUint32(key string, value uint32) Context
	// AppendUint64 adds an integer value for a specific key to this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendUint64(key string, value uint64) Context
	// AppendFloat32 adds a floating point number value for a specific key to
	// this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendFloat32(key string, value float32) Context
	// AppendFloat64 adds a floating point number value for a specific key to
	// this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendFloat64(key string, value float64) Context
	// AppendTime adds a timestamp value for a specific key to
	// this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendTime(key string, value time.Time) Context
	// AppendDuration adds a time duration value for a specific key to
	// this context.
	//
	// Calling this method multiple times with the same key may lead to
	// unexpected behaviour.
	AppendDuration(key string, value time.Duration) Context
}

type DoneFunc func(message string)

type Event interface {
	// Messagef submits this log event to the different sinks using a formatted
	// message. The formatting is the same applied from the fmt package.
	Messagef(format string, args ...any)

	// Message submits this log event to the different sinks using a message. To
	// submit without a message you may pass an empty string into this method, like
	// so:
	// 	ev.WithString("hello", "world").Message("")
	Message(message string)

	// WithFunc applies a function to the event and then forwards the return value.
	//
	// Useful for reusing "with statements" for multiple logs.
	WithFunc(f func(Event) Event) Event

	// WithCaller adds a caller field to the log contexts inside this log event.
	//
	// This method is called automatically by NewEvent and all Logger methods,
	// though you can override the value set there by calling it again manually.
	//
	// It's up to the logger sink to decide how this error is rendered in the log
	// message. Commonly, but not necessarily, this is rendered as fields with names
	// "caller" and "line".
	WithCaller(file string, line int) Event

	// WithString adds a string field to this logged message. Calling this method
	// multiple times with the same key may lead to unexpected behaviour.
	WithString(key string, value string) Event

	// WithStringf adds a formatted string field to this logged message. The
	// formatting is the same applied from the fmt package. Calling this method
	// multiple times with the same key may lead to unexpected behaviour.
	WithStringf(key string, format string, args ...any) Event

	// WithStringer adds a string field to this logged message using the value
	// from fmt.Stringer.String(). Calling this method multiple times with the
	// same key may lead to unexpected behaviour.
	WithStringer(key string, value fmt.Stringer) Event

	// WithRune adds a rune field to this logged message. Calling this method
	// multiple times with the same key may lead to unexpected behaviour.
	WithRune(key string, value rune) Event

	// WithBool adds a boolean field to this logged message. Calling this method
	// multiple times with the same key may lead to unexpected behaviour.
	WithBool(key string, value bool) Event

	// WithInt adds an integer field to this logged message. Calling this method
	// multiple times with the same key may lead to unexpected behaviour.
	WithInt(key string, value int) Event

	// WithInt64 adds an integer field to this logged message. Calling this method
	// multiple times with the same key may lead to unexpected behaviour.
	WithInt64(key string, value int64) Event

	// WithInt32 adds an integer field to this logged message. Calling this method
	// multiple times with the same key may lead to unexpected behaviour.
	WithInt32(key string, value int32) Event

	// WithUint adds an integer field to this logged message. Calling this method
	// multiple times with the same key may lead to unexpected behaviour.
	WithUint(key string, value uint) Event

	// WithUint64 adds an integer field to this logged message. Calling this method
	// multiple times with the same key may lead to unexpected behaviour.
	WithUint64(key string, value uint64) Event

	// WithUint32 adds an integer field to this logged message. Calling this method
	// multiple times with the same key may lead to unexpected behaviour.
	WithUint32(key string, value uint32) Event

	// WithFloat32 adds a floating point number field to this logged message. Calling
	// this method multiple times with the same key may lead to unexpected behaviour.
	WithFloat32(key string, value float32) Event

	// WithFloat64 adds a floating point number field to this logged message. Calling
	// this method multiple times with the same key may lead to unexpected behaviour.
	WithFloat64(key string, value float64) Event

	// WithError adds an error field to this logged message. Calling this method
	// multiple times may lead to unexpected behaviour.
	//
	// It's up to the logger sink to decide how this error is rendered in the log
	// message. Commonly, but not necessarily, this is rendered as a field with name
	// "error".
	WithError(value error) Event

	// WithTime adds a timestamp field to this logged message. Calling
	// this method multiple times with the same key may lead to unexpected behaviour.
	//
	// It's up to the logger sink to decide how this error is rendered in the log
	// message, e.g. in UNIX timestamp integer form or string formatted datetime.
	WithTime(key string, value time.Time) Event

	// WithDuration adds a timestamp field to this logged message. Calling
	// this method multiple times with the same key may lead to unexpected behaviour.
	//
	// It's up to the logger sink to decide how this error is rendered in the log
	// message, e.g. in milliseconds integer form or string formatted duration.
	WithDuration(key string, value time.Duration) Event
}

type Level byte

type Logger interface {
	// Debug creates a new event using new contexts from all registered sinks of
	// "debugging" logging level or higher.
	Debug() Event
	// Info creates a new event using new contexts from all registered sinks of
	// "information" logging level or higher.
	Info() Event
	// Warn creates a new event using new contexts from all registered sinks of
	// "warning" logging level or higher.
	Warn() Event
	// Error creates a new event using new contexts from all registered sinks of
	// "error" logging level or higher.
	Error() Event
	// Panic creates a new event using new contexts from all registered sinks of
	// "panic" logging level or higher.
	//
	// Compared to the other logging events, after submitting the logged
	// messages this method calls panic with the final message string.
	Panic() Event
}

type Mock struct {
	// Logs is an array of logs recorded. Each logged event is stored as a
	// separate item in this array.
	Logs []MockLog
	// LogMessages is an array of log messages recorded. This complements the
	// array of MockLog for easier assertion that the expected messages have been
	// logged. Empty messages are also stored in this array as empty strings.
	LogMessages []string
}

type MockLog struct {
	// Level is the logging level that was used. If calling MockLogger.Debug(),
	// then this field holds the value of LevelDebug.
	Level Level
	// Message is the final message that was used to submit this logged event.
	Message string
	// Fields holds each field added to this logged event, in addition to the
	// following fields:
	//
	// 	Event.SetScope("foo")   => MockLog.Fields["scope"] = "foo"
	// 	Event.SetError(someErr) => MockLog.Fields["error"] = someErr
	// 	Event.SetCaller("foo", 42)
	// 		=> MockLog.Fields["caller"] = "foo"
	// 		=> MockLog.Fields["line"] = 42
	Fields map[string]any
	// FieldsAdded is a slice of strings with all the keys added to the Fields
	// map. This includes the custom mapping of Event.SetScope,
	// Event.SetError, and Event.SetCaller as mentioned in the Fields docs.
	//
	// If a field is added more than one time, then it will show up in this list
	// equally many times. Useful for checking if fields are misstakenly added
	// multiple times.
	FieldsAdded []string
}

type Sink interface {
	NewContext(scope string) Context
}