loglayer

type BeforeDataOutParams struct {
	LogLevel LogLevel
	// Data is the assembled fields + error map. May be nil if the entry
	// has no fields and no error.
	Data Data
	// Fields is the logger's persistent fields, as the core sees them
	// (after OnFieldsCalled has already run at registration time).
	Fields Fields
	// Metadata is the value the user passed to WithMetadata, after any
	// OnMetadataCalled mutations.
	Metadata any
	// Err is the error attached via WithError, or nil.
	Err error
	// Ctx is the per-call context.Context attached via WithContext, or nil.
	Ctx context.Context
	// Groups mirrors [TransportParams.Groups].
	Groups []string
	// Schema mirrors [TransportParams.Schema].
	Schema Schema
	// Prefix mirrors [TransportParams.Prefix]: the value attached
	// via WithPrefix on the emitting logger (or set on Config.Prefix
	// at construction). Empty when no prefix was set. Read-only for
	// hooks; the framework propagates this value unchanged through
	// the dispatch path.
	Prefix string
}

type BeforeMessageOutParams struct {
	LogLevel LogLevel
	Messages []any
	// Ctx is the per-call context.Context attached via WithContext, or nil.
	Ctx context.Context
	// Groups mirrors [TransportParams.Groups].
	Groups []string
	// Schema mirrors [TransportParams.Schema].
	Schema Schema
	// Prefix mirrors [TransportParams.Prefix]: the value attached
	// via WithPrefix on the emitting logger (or set on Config.Prefix
	// at construction). Empty when no prefix was set. Read-only for
	// hooks; the framework propagates this value unchanged through
	// the dispatch path.
	Prefix string
}

type Config struct {
	// Transport is a convenience for the single-transport case. Mutually
	// exclusive with Transports; setting both panics with
	// ErrTransportAndTransports (or returns it from Build).
	Transport Transport
	// Transports is a slice for the multi-transport case. Mutually exclusive
	// with Transport.
	Transports []Transport

	// Plugins are added to the logger at construction time, in slice order.
	// Equivalent to calling AddPlugin for each entry after construction;
	// either form is fine.
	Plugins []Plugin

	// Prefix is exposed verbatim on TransportParams.Prefix and on
	// every dispatch-time plugin hook param struct. Transports
	// decide how to render it: most call
	// transport.JoinPrefixAndMessages to fold it into the first
	// message string; cli renders it in dim grey separate from
	// the level color. Equivalent to calling WithPrefix on the
	// freshly-constructed logger.
	Prefix string

	// Disabled suppresses all log output when true. Defaults to false
	// (logging on). Equivalent to calling DisableLogging() after construction.
	Disabled bool

	// ErrorSerializer customizes how errors are serialized into the log data.
	ErrorSerializer ErrorSerializer

	// ErrorFieldName is the key used for the serialized error in log data. Defaults to "err".
	ErrorFieldName string

	// CopyMsgOnOnlyError copies err.Error() as the log message when calling ErrorOnly.
	CopyMsgOnOnlyError bool

	// FieldsKey nests all persistent fields under this key. If empty, fields are merged at root.
	FieldsKey string

	// MetadataFieldName nests the per-call metadata value under this key in
	// the assembled output. If empty, transports use their default placement
	// policy (renderer transports flatten map metadata at root; wrapper
	// transports flatten map metadata to attributes and nest non-map metadata
	// under a transport-specific default key, typically "metadata").
	//
	// When non-empty, the entry's metadata (whether a map, struct, scalar,
	// or slice) is nested under this single key uniformly, and transports
	// honor that placement.
	MetadataFieldName string

	// MuteFields disables inclusion of persistent fields in log output.
	MuteFields bool

	// MuteMetadata disables inclusion of metadata in log output.
	MuteMetadata bool

	// DisableFatalExit prevents the library from calling os.Exit(1) after a
	// Fatal-level log is dispatched. Defaults to false (Fatal exits, matching
	// the Go convention used by log.Fatal, zerolog, zap, logrus, and others).
	//
	// Set to true in tests, library code that shouldn't terminate the host
	// process, or any context where os.Exit would be inappropriate.
	//
	// Note: a few logger-wrapper transports (notably phuslu) may still trigger
	// their underlying library's exit before this option takes effect. See
	// each wrapper's docs for details.
	DisableFatalExit bool

	// TransportCloseTimeout caps how long the framework waits for an
	// io.Closer transport to drain on removal (RemoveTransport,
	// SetTransports, AddTransport-by-replace) or pre-Fatal flush, so a
	// wedged endpoint can't hang the process or mutator goroutine.
	// Defaults to 5 seconds when zero or negative.
	TransportCloseTimeout time.Duration

	// OnTransportPanic is called when a transport's SendToLogger panics.
	// The dispatch loop recovers the panic so a buggy transport can't
	// crash the host application from inside a log call, then continues
	// to the next transport.
	//
	// The argument is a [*RecoveredPanicError] with Kind = PanicKindTransport
	// and Hook = the panicking transport's ID. This matches the shape
	// passed to plugin [ErrorReporter.OnError] callbacks so a single
	// observability handler can absorb panics from either source.
	//
	// Default (nil): no recover wrap; a panicking transport propagates
	// up through the emission call (matching the convention used by
	// zerolog/zap/log/slog). Set this to plumb panics into your own
	// observability (a metrics counter, an error tracker, a separate
	// logger). A panic from inside this callback is itself recovered
	// (and dropped) so a buggy reporter can't take down the dispatch
	// loop.
	OnTransportPanic func(err *RecoveredPanicError)

	// Source configures call-site capture (file/line/function) per emission.
	// Off by default; see [SourceConfig] for the cost.
	Source SourceConfig

	// Routing configures group-based dispatch (named routing rules,
	// active-groups filter, behavior for ungrouped entries). The zero
	// value disables group routing entirely (every transport receives
	// every entry).
	Routing RoutingConfig
}

type CopyMsgPolicy uint8

type Data map[string]any

type DataHook interface {
	OnBeforeDataOut(BeforeDataOutParams) Data
}

type ErrorOnlyOpts struct {
	// LogLevel overrides the default error level. Defaults to LogLevelError.
	LogLevel LogLevel

	// CopyMsg overrides Config.CopyMsgOnOnlyError for this call. Zero
	// value (CopyMsgDefault) keeps the config default.
	CopyMsg CopyMsgPolicy
}

type ErrorReporter interface {
	OnError(err error)
}

type ErrorSerializer func(err error) map[string]any

type F = Fields

type Fields map[string]any

type FieldsHook interface {
	OnFieldsCalled(fields Fields) Fields
}

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

type LevelHook interface {
	TransformLogLevel(TransformLogLevelParams) (LogLevel, bool)
}

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

type LogGroup struct {
	// Transports lists the IDs of transports this group routes to.
	// Required for the group to do anything.
	Transports []string

	// Level is the minimum log level for this group. Entries below this
	// level are dropped for this group's transports. Zero value means "no
	// per-group filter: all levels pass" (the levelIndex check rejects 0
	// as an unknown level).
	Level LogLevel

	// Disabled suppresses this group's routing when true. Entries tagged
	// only with disabled groups are dropped. Entries tagged with both a
	// disabled and an enabled group still route through the enabled one.
	//
	// (Contrast with an undefined group name in the tag list: if every
	// tag refers to an undefined group, the entry falls back to
	// UngroupedRouting. Disabled is "explicitly off"; undefined is
	// "treated as no tag.")
	Disabled bool
}

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

type LogLevel int

type M = Metadata

type MessageHook interface {
	OnBeforeMessageOut(BeforeMessageOutParams) []any
}

type Metadata map[string]any

type MetadataHook interface {
	OnMetadataCalled(metadata any) any
}

type MetadataOnlyOpts struct {
	// LogLevel overrides the default info level. Defaults to LogLevelInfo.
	LogLevel LogLevel
}

type Plugin interface {
	ID() string
}

type PluginPanicDetails struct {
	// Hook is the hook method that panicked, e.g. "OnBeforeDataOut".
	Hook string
}

type RawLogEntry struct {
	LogLevel LogLevel
	Messages []any
	// Metadata is per-entry data. Accepts any value: structs, maps, or any other type.
	// Serialization is handled by the transport.
	Metadata any
	Err      error
	// Fields overrides the logger's persistent fields for this entry. If nil
	// the logger's current fields are used.
	Fields Fields
	// Ctx is an optional Go context.Context for the entry; surfaced to transports
	// via TransportParams.Ctx. Use it to carry trace IDs, deadlines, or anything
	// else a transport may extract.
	Ctx context.Context
	// Groups overrides the logger's assigned group tags for routing. Nil
	// uses the logger's groups (set via WithGroup).
	Groups []string
	// Source overrides the captured source info for this entry. Set this
	// from adapters that already have source info (e.g. the slog handler
	// extracts it from slog.Record.PC). Nil falls back to runtime capture
	// when Config.Source.Enabled is true; otherwise no source info is recorded.
	Source *Source
}

type RecoveredPanicError struct {
	Kind   string
	ID     string
	Plugin *PluginPanicDetails
	Value  any
	// contains filtered or unexported fields
}

type RoutingConfig struct {
	// Groups defines named routing rules. Each group lists the transport
	// IDs it routes to, an optional minimum level, and an optional
	// disabled flag. Tag entries with a group via WithGroup to limit
	// dispatch to that group's transports.
	Groups map[string]LogGroup

	// ActiveGroups, when non-empty, restricts routing to only these
	// groups. Logs tagged with groups not in this list are dropped (or
	// fall back to Ungrouped if none of the entry's groups are active).
	// Nil/empty means "no filter: all defined groups are active".
	ActiveGroups []string

	// Ungrouped controls what happens to entries with no group tag
	// when Groups is configured. Zero value (Mode: UngroupedToAll)
	// preserves the no-routing behavior of every transport receiving
	// every ungrouped entry.
	Ungrouped UngroupedRouting
}

type Schema struct {
	// FieldsKey is non-empty when the persistent fields are nested under
	// this key inside Data. When empty, fields are merged at root.
	FieldsKey string
	// MetadataFieldName is non-empty when the entry's metadata should
	// nest under this key uniformly (both map and non-map values).
	// When empty, each transport applies its default placement policy.
	MetadataFieldName string
	// ErrorFieldName is the key under which the serialized error map
	// lives in Data. Always populated; defaults to "err".
	ErrorFieldName string
	// SourceFieldName is the key under which call-site source info lives
	// in Data when [Config.Source.Enabled] is true. Always populated;
	// defaults to "source".
	SourceFieldName string
}

type SendGate interface {
	ShouldSend(ShouldSendParams) bool
}

type ShouldSendParams struct {
	// TransportID is the ID of the transport this dispatch would target.
	// Use it to selectively gate per-transport (e.g. send debug to console
	// but not to the shipping transport).
	TransportID string
	LogLevel    LogLevel
	Messages    []any
	Data        Data
	Fields      Fields
	Metadata    any
	Err         error
	// Ctx is the per-call context.Context attached via WithContext, or nil.
	Ctx context.Context
	// Groups mirrors [TransportParams.Groups].
	Groups []string
	// Schema mirrors [TransportParams.Schema].
	Schema Schema
	// Prefix mirrors [TransportParams.Prefix]: the value attached
	// via WithPrefix on the emitting logger (or set on Config.Prefix
	// at construction). Empty when no prefix was set. Read-only for
	// hooks; the framework propagates this value unchanged through
	// the dispatch path.
	Prefix string
}

type Source struct {
	Function string `json:"function,omitempty"`
	File     string `json:"file,omitempty"`
	Line     int    `json:"line,omitempty"`
}

type SourceConfig struct {
	// Enabled captures the call site (file/line/function) of every log
	// emission via runtime.Caller and includes it in the assembled Data
	// under FieldName. Off by default; opt in for production-debuggable
	// output. Costs about 620 ns and 5 extra allocations per emission
	// on amd64 (see Benchmarks). Paid only when this is true; the
	// dispatch path is untouched otherwise.
	//
	// Adapters that already have source information (notably the slog
	// handler, which extracts it from slog.Record.PC) can supply it via
	// RawLogEntry.Source without setting Enabled.
	Enabled bool

	// FieldName is the key under which the captured Source is rendered
	// in the assembled Data. Defaults to "source" to match the slog
	// convention.
	FieldName string
}

type TransformLogLevelParams struct {
	LogLevel LogLevel
	Data     Data
	Messages []any
	Fields   Fields
	Metadata any
	Err      error
	// Ctx is the per-call context.Context attached via WithContext, or nil.
	Ctx context.Context
	// Groups mirrors [TransportParams.Groups].
	Groups []string
	// Schema mirrors [TransportParams.Schema].
	Schema Schema
	// Prefix mirrors [TransportParams.Prefix]: the value attached
	// via WithPrefix on the emitting logger (or set on Config.Prefix
	// at construction). Empty when no prefix was set. Read-only for
	// hooks; the framework propagates this value unchanged through
	// the dispatch path.
	Prefix string
}

type Transport interface {
	// ID returns the unique identifier for this transport.
	ID() string

	// IsEnabled returns whether the transport is currently active.
	IsEnabled() bool

	// SendToLogger receives a fully assembled log entry and dispatches it.
	// Implementations should perform their own level filtering if needed.
	SendToLogger(params TransportParams)

	// GetLoggerInstance returns the underlying logger instance, if any.
	// Returns nil for transports that have no underlying library.
	GetLoggerInstance() any
}

type TransportParams struct {
	LogLevel LogLevel
	Messages []any
	// Data holds the assembled persistent fields and error. Nil when no
	// fields are set and no error is attached. Use len(Data) > 0 to test.
	Data Data
	// Metadata is the raw value passed to WithMetadata. May be a struct, map,
	// or any other type. Nil if WithMetadata was not called or metadata is muted.
	Metadata any
	Err      error
	// Fields is the logger's persistent key/value bag, raw (not yet folded into Data).
	Fields Fields
	// Ctx is the per-call context.Context attached via WithContext, if any.
	// Transports can use it to extract trace IDs, span context, deadlines, etc.
	// Nil when no Go context was attached.
	Ctx context.Context
	// Groups holds the entry's group tags (persistent WithGroup first,
	// per-call WithGroup appended, deduped). Nil when no groups apply.
	// Routing has already consumed the slice before this point; it's
	// exposed so transports can include it in the wire payload.
	Groups []string
	// Schema is the resolved assembly shape (FieldsKey, MetadataFieldName,
	// ErrorFieldName, SourceFieldName). Use it to navigate Data and to
	// decide metadata placement.
	Schema Schema
	// Prefix is the value attached via WithPrefix on the emitting
	// logger (or set on Config.Prefix at construction), exposed
	// verbatim so transports can render it independently from the
	// message (e.g. tinted differently, emitted as a structured
	// field, rendered in its own column).
	//
	// Empty string when no prefix was set.
	//
	// Transports that want a "prefix folded into Messages[0]"
	// rendering call [transport.JoinPrefixAndMessages] at the top
	// of SendToLogger; the helper has fast-path early returns for
	// the no-prefix case, so the per-call cost on a logger that
	// hasn't called WithPrefix is one string compare.
	Prefix string
}

type UngroupedMode uint8

type UngroupedRouting struct {
	// Mode selects the routing strategy. Zero value is UngroupedToAll.
	Mode UngroupedMode
	// Transports is the allowlist used when Mode == UngroupedToTransports.
	// Ignored for the other modes.
	Transports []string
}