handler

type BaseHandler struct {
	// contains filtered or unexported fields
}

type BaseOption func(*BaseOptions) error

type BaseOptions struct {
	Level  LogLevel  // Minimum log level
	Output io.Writer // Output writer

	// Format specifies the output format (e.g., "json", "text").
	// Optional if ValidFormats is empty (handler doesn't support format selection).
	// When ValidFormats is provided but Format is empty, defaults to ValidFormats[0].
	Format string

	// ValidFormats lists accepted format strings for this handler.
	// If provided, Format must be one of these values or empty (uses first as default).
	// Leave empty if handler doesn't support format configuration.
	ValidFormats []string

	WithCaller bool   // True if caller information should be included
	WithTrace  bool   // True if stack traces should be included
	CallerSkip int    // User-specified caller skip frames
	Separator  string // Key prefix separator (default: "_")
}

type CallerAdjuster interface {
	Handler

	// WithCallerSkip returns a new CallerAdjuster with the absolute
	// user-visible caller skip set. Negative skip values are clamped to zero.
	WithCallerSkip(skip int) CallerAdjuster

	// WithCallerSkipDelta returns a new CallerAdjuster with the caller skip
	// adjusted by delta.
	// The delta is applied relative to the current skip. Zero delta is a no-op.
	// If the new skip is negative, it is clamped to zero.
	WithCallerSkipDelta(delta int) CallerAdjuster
}

type Chainer interface {
	Handler

	// WithAttrs returns a new Chainer with the given key-value pairs added.
	// It returns the original handler if no key-value pairs are provided.
	WithAttrs(keyValues []any) Chainer

	// WithGroup returns a new Chainer that qualifies subsequent attribute keys
	// with the group name. It returns the original handler if the name is empty.
	WithGroup(name string) Chainer
}

type ComplianceChecker interface {
	// CheckEnabled verifies that the handler correctly implements the Enabled method.
	// Returns an error if the handler is not enabled at InfoLevel.
	CheckEnabled(h Handler) error

	// CheckHandle verifies that the handler correctly processes log records.
	// Returns an error if Handle returns an error for a valid record.
	CheckHandle(h Handler, r *Record) error

	// CheckChainer verifies that the handler correctly implements the Chainer interface.
	// Returns an error if WithAttrs or WithGroup return nil.
	// This method should only be called if the handler implements Chainer.
	CheckChainer(c Chainer) error
}

type Configurable interface {
	Handler

	// WithLevel returns a new Configurable with a new minimum level applied.
	// It returns the original handler if the level value is unchanged.
	WithLevel(level LogLevel) Configurable

	// WithOutput returns a new Configurable with the output writer set permanently.
	// It returns the original handler if the writer value is unchanged.
	WithOutput(w io.Writer) Configurable
}

type Feature uint32

type FeatureToggler interface {
	Handler

	// WithCaller returns a new FeatureToggler that enables or disables caller resolution.
	// It returns the original handler if the enabled value is unchanged.
	// By default, caller resolution is disabled.
	WithCaller(enabled bool) FeatureToggler

	// WithTrace returns a new FeatureToggler that enables or disables trace logging.
	// It returns the original handler if the enabled value is unchanged.
	// By default, trace logging is disabled.
	WithTrace(enabled bool) FeatureToggler
}

type Handler interface {
	// Handle processes a log record. Must handle nil context gracefully.
	//
	// IMPORTANT: The Record pointer and its slice fields (KeyValues) are only
	// valid for the duration of this call. Handlers must not retain the
	// *Record pointer or alias the KeyValues slice backing array after returning.
	// If retention is needed, data must be copied.
	//
	// Returns error only for unrecoverable failures (disk full, etc.).
	Handle(ctx context.Context, record *Record) error

	// Enabled reports whether the handler processes records at the given level.
	// Called before building expensive Record objects.
	Enabled(level LogLevel) bool

	// HandlerState returns an immutable HandlerState that exposes handler state.
	HandlerState() HandlerState

	// Features returns the handler's supported features.
	//
	// MUST return a stable value; concurrent calls must be safe.
	// Handler implementations should compute features once at initialization.
	Features() HandlerFeatures
}

type HandlerFeatures struct {
	// contains filtered or unexported fields
}

type HandlerState interface {
	// CallerEnabled returns whether caller information should be included.
	CallerEnabled() bool

	// TraceEnabled returns whether stack traces should be included for error-level logs.
	TraceEnabled() bool

	// CallerSkip returns the current caller skip value.
	CallerSkip() int
}

type LevelMapper[T any] struct {
	// contains filtered or unexported fields
}

type LogLevel int32

type MutableConfig interface {
	Handler

	// SetLevel changes the minimum log level that will be processed.
	SetLevel(level LogLevel) error

	// SetOutput changes the destination for log output.
	SetOutput(w io.Writer) error
}

type Record struct {
	// Time is the timestamp of the log entry.
	Time time.Time

	// Level is the log level of the log entry.
	Level LogLevel

	// Message is the log message.
	Message string

	// KeyValues is the list of attributes associated with the log entry.
	KeyValues []any

	// PC is the program counter for source location (0 if unavailable).
	// It will be used for loggers that don't support source location natively.
	PC uintptr

	// Skip is the number of stack frames to skip for source location.
	// It will be used for loggers that support source location natively.
	Skip int
}

type StateFlag uint32

type Syncer interface {
	Handler

	// Sync flushes buffered log entries. Returns error on flush failure.
	Sync() error
}