001package io.jstach.rainbowgum;
002
003import java.lang.System.Logger.Level;
004import java.time.Instant;
005import java.util.ArrayList;
006import java.util.Arrays;
007import java.util.Collection;
008import java.util.EnumSet;
009import java.util.List;
010import java.util.Locale;
011import java.util.Objects;
012import java.util.Set;
013import java.util.concurrent.atomic.AtomicBoolean;
014import java.util.concurrent.atomic.AtomicLong;
015import java.util.concurrent.locks.ReentrantLock;
016
017import org.jspecify.annotations.NonNull;
018import org.jspecify.annotations.Nullable;
019
020import io.jstach.rainbowgum.annotation.CaseChanging;
021
022/**
023 * Appenders are guaranteed to be written synchronously much like an actor in actor
024 * concurrency. They safely hold onto and communicate with the encoder and output.
025 * Appenders largely deal with correct locking, buffer reuse and flushing.
026 * {@linkplain LogAppender.AppenderFlag Flags } can be set to control the behavior the
027 * appenders and publishers can request different appender behavior through the flags.
028 *
029 * @see LogAppender.AppenderFlag
030 * @apiNote because appenders require complicated implementation and to guarantee
031 * integrity the implementations are encapsulated (sealed).
032 */
033public sealed interface LogAppender extends LogLifecycle {
034
035        /**
036         * Default Console appender name.
037         */
038        static final String CONSOLE_APPENDER_NAME = "console";
039
040        /**
041         * Removes the current thread's encoding buffers from every appender of the globally
042         * bound {@link RainbowGum}, so a pooled thread does not keep a buffer it may never
043         * use again. Only {@link AppenderType#LOCK_THREAD_LOCAL_BUFFER} and
044         * {@link AppenderType#SYNCHRONIZED_THREAD_LOCAL_BUFFER} appenders keep per thread
045         * buffers; the next event the thread logs simply creates a new one. Does nothing if
046         * no Rainbow Gum is bound. Logging context such as MDC is cleared separately with
047         * {@link LogEventFactory.KeyValuesContributor#clear()}.
048         * {@snippet :
049         * LogAppender.clearThreadLocals();
050         * KeyValuesContributor.global().clear();
051         * }
052         */
053        public static void clearThreadLocals() {
054                var gum = RainbowGumHolder.peek();
055                if (gum == null) {
056                        return;
057                }
058                for (var appender : gum.config().serviceRegistry().find(LogAppender.class)) {
059                        InternalLogAppender.of(appender).clearThreadLocals();
060                }
061        }
062
063        /**
064         * Default output file appender name.
065         */
066        static final String FILE_APPENDER_NAME = "file";
067
068        /**
069         * Output appender property.
070         */
071        static final String APPENDER_OUTPUT_PROPERTY = LogProperties.APPENDER_OUTPUT_PROPERTY;
072
073        /**
074         * Encoder appender property.
075         */
076        static final String APPENDER_ENCODER_PROPERTY = LogProperties.APPENDER_ENCODER_PROPERTY;
077
078        /**
079         * Appender flags. A list of flags (usually comma separated).
080         * @see AppenderFlag
081         */
082        static final String APPENDER_FLAGS_PROPERTY = LogProperties.APPENDER_FLAGS_PROPERTY;
083
084        /**
085         * Appender type.
086         * @see AppenderType
087         */
088        static final String APPENDER_TYPE_PROPERTY = LogProperties.APPENDER_TYPE_PROPERTY;
089
090        /**
091         * Batch of events. <strong>DO NOT MODIFY THE ARRAY</strong>. Do not use the
092         * <code>length</code> of the passed in array but instead use <code>count</code>
093         * parameter.
094         * @param events an array guaranteed to be smaller than count.
095         * @param count the number of items.
096         */
097        public void append(LogEvent[] events, int count);
098
099        /**
100         * Appends a single event.
101         * @param event event.
102         */
103        public void append(LogEvent event);
104
105        /**
106         * Boolean like flags for appender that can be set with
107         * {@link LogAppender#APPENDER_FLAGS_PROPERTY}. Unlike {@link AppenderType} more than
108         * one flag can be set at once.
109         */
110        @CaseChanging
111        public enum AppenderFlag {
112
113                /**
114                 * By default the appender will call flush on each item appended or if in async
115                 * batch mode for each batch. This flag disables that behavior so that flushing is
116                 * left up to the output (or an external mechanism) instead.
117                 */
118                DISABLE_IMMEDIATE_FLUSH,
119                /**
120                 * The appender will drop events on reentry which happens if an appender during
121                 * its append causes recursive appending in the same thread. This is an analog to
122                 * what
123                 * <a href="https://logback.qos.ch/manual/appenders.html#AppenderBase">Logback
124                 * does by default</a>. Detection uses the appender's lock or monitor. Appenders
125                 * that reuse a thread local buffer also detect reentry during encoding.
126                 * {@link AppenderType#LOCK_NEW_BUFFER} only detects reentry while writing under
127                 * its lock. <strong>Dropping is not enabled by default.</strong>
128                 * <p>
129                 * This flag is to allow outputs that do logging themselves. For performance
130                 * reasons and to allow async publishers it is recommended that you fix the output
131                 * code such that it does not do logging. This flag is ignored if
132                 * {@link #REENTRY_LOG} is set.
133                 * <p>
134                 * <strong>This flag will not fix outputs causing lool like logging if an async
135                 * publisher is used!</strong> That is why it is recommended you fix the output by
136                 * dropping events that would cause infinite loop like logging.
137                 * @see #REENTRY_LOG
138                 */
139                REENTRY_DROP,
140                /**
141                 * The appender will log events as errors to std error on reentry which happens if
142                 * an appender during its append causes recursive appending in the same thread.
143                 * This is an analog to what
144                 * <a href="https://logback.qos.ch/manual/appenders.html#AppenderBase">Logback
145                 * does by default</a>. Detection is the same as {@link #REENTRY_DROP} and is not
146                 * enabled by default. This flag is to resolve failures of outputs that then do
147                 * logging.
148                 * <p>
149                 * This flag takes precedence over {@link #REENTRY_DROP}.
150                 */
151                REENTRY_LOG;
152
153                static Set<AppenderFlag> parse(Collection<String> value) {
154                        if (value.isEmpty()) {
155                                return EnumSet.noneOf(AppenderFlag.class);
156                        }
157                        var s = EnumSet.noneOf(AppenderFlag.class);
158                        for (var v : value) {
159                                s.add(parse(v));
160                        }
161                        return s;
162                }
163
164                static AppenderFlag parse(String value) {
165                        return LogProperty.enumValue(AppenderFlag.class, value);
166                }
167
168        }
169
170        /**
171         * The buffer/locking strategy an appender uses. Unlike {@link AppenderFlag} exactly
172         * one is in effect for a given appender - set on the {@link LogAppender.Builder} (or
173         * via {@link LogAppender#APPENDER_TYPE_PROPERTY}) at construction time and fixed for
174         * the appender's lifetime; a publisher cannot change it afterward.
175         */
176        @CaseChanging
177        public enum AppenderType {
178
179                /**
180                 * The appender will create a single buffer that will be reused and will be
181                 * protected by the appenders locking.
182                 */
183                REUSE_BUFFER,
184                /**
185                 * The appender will give each thread its own reusable buffer (a
186                 * {@link ThreadLocal}) instead of allocating a new buffer per event. Encoding is
187                 * done <strong>outside</strong> the appender's lock (the thread's buffer is only
188                 * visited by that thread so no protection is needed while encoding) with the lock
189                 * only held for the final write to the output.
190                 * <p>
191                 * The same {@link ThreadLocal} buffer is used regardless of whether the calling
192                 * thread is a platform or virtual thread. A virtual thread's entry becomes
193                 * collectible once the thread itself terminates, and a typical unit of work (e.g.
194                 * one HTTP request) logs several times on the same thread, so reusing the buffer
195                 * across those calls still pays off even for short-lived virtual threads.
196                 * <p>
197                 * This is the default type - see {@link #SYNCHRONIZED_THREAD_LOCAL_BUFFER} for
198                 * the alternative lock-kind opt-in.
199                 */
200                LOCK_THREAD_LOCAL_BUFFER,
201                /**
202                 * Like {@link #LOCK_THREAD_LOCAL_BUFFER} (a reused per-thread buffer, encoding
203                 * done outside any lock) except the final write to the output is protected by a
204                 * plain {@code synchronized} block (the JVM's intrinsic monitor) instead of a
205                 * {@link ReentrantLock}.
206                 * <p>
207                 * The Java language has no way to acquire a monitor in one method call and
208                 * release it in another, so this appender's critical sections are written as
209                 * literal {@code synchronized} blocks rather than going through a shared lock
210                 * abstraction the way {@link #LOCK_THREAD_LOCAL_BUFFER} does.
211                 * {@link AppenderFlag#REENTRY_DROP} and {@link AppenderFlag#REENTRY_LOG} are
212                 * still honored though - {@link Thread#holdsLock(Object)} is the
213                 * {@code synchronized} equivalent of {@code ReentrantLock}'s
214                 * {@code isHeldByCurrentThread()}, so reentrancy is detected the same way.
215                 * <p>
216                 * Motivated by Log4j2's own garbage-free appenders using {@code synchronized}
217                 * rather than a {@code java.util.concurrent} lock around their buffer-transfer
218                 * step, and confirmed by real-workload benchmarking to outperform
219                 * {@link ReentrantLock} under platform-thread contention - this was the default
220                 * for a time. Real-workload benchmarking under virtual threads found the
221                 * opposite, a large and reproducible loss versus {@link ReentrantLock} for
222                 * reasons not fully understood (classic JEP 491 pinning was checked and ruled
223                 * out), so {@link #LOCK_THREAD_LOCAL_BUFFER} is the default now and this type is
224                 * an opt-in for platform-thread-heavy deployments that want the edge.
225                 * <p>
226                 * {@link LogConfig.Globals#appenderLock()} decides whether this type is honored:
227                 * {@link LogConfig.Globals.AppenderLock#REENTRANT}, and the default
228                 * {@link LogConfig.Globals.AppenderLock#AUTO} before JDK 24 (where
229                 * {@code synchronized} pins a virtual thread's carrier, see
230                 * <a href="https://openjdk.org/jeps/491">JEP 491</a>), turn it into
231                 * {@link #LOCK_THREAD_LOCAL_BUFFER}.
232                 */
233                SYNCHRONIZED_THREAD_LOCAL_BUFFER,
234                /**
235                 * Like {@link #LOCK_THREAD_LOCAL_BUFFER} (encoding done outside the lock, the
236                 * lock only guards the final write to the output) except the buffer is allocated
237                 * fresh for every single event instead of being cached in a {@link ThreadLocal}.
238                 * <p>
239                 * For deployments that want a hard guarantee of never using {@link ThreadLocal}
240                 * anywhere in the logging path - {@link #REUSE_BUFFER} is the existing
241                 * no-{@code ThreadLocal} option, but it holds its lock across the entire
242                 * encode-then-write critical section (the single shared buffer must stay
243                 * protected for as long as anything is writing into it), so it pays for that
244                 * guarantee with lock contention proportional to encoding cost, not just I/O
245                 * cost. This type keeps {@link #LOCK_THREAD_LOCAL_BUFFER}'s low-contention shape
246                 * (encode into a buffer nothing else can see, lock only for the write) while
247                 * dropping the {@link ThreadLocal} - the buffer is simply a local variable, not
248                 * cached anywhere, so nothing needs to be evicted or leaked-if-forgotten either.
249                 * The tradeoff is a fresh buffer allocation (and whatever it grows to internally)
250                 * on every single event instead of amortizing that allocation across a thread's
251                 * whole lifetime.
252                 * @apiNote not the default - {@link #LOCK_THREAD_LOCAL_BUFFER}'s reused buffer is
253                 * the better choice unless avoiding {@link ThreadLocal} entirely is a hard
254                 * requirement, not just a preference.
255                 */
256                LOCK_NEW_BUFFER,
257                /*
258                 * Real-workload benchmarking under virtual threads found
259                 * SYNCHRONIZED_THREAD_LOCAL_BUFFER and LOCK_THREAD_LOCAL_BUFFER each winning by a
260                 * real, repeatable, double-digit-percentage margin on their own platform (native
261                 * image, HotSpot respectively) and losing by a comparable margin on the other - a
262                 * genuine cross-over, not just a shrinking gap, so no single fixed choice serves
263                 * both well. Matters most for something distributed as more than one build of the
264                 * same artifact for the same deployment - a native executable and a plain jar,
265                 * say - where picking correctly per build would otherwise mean either shipping
266                 * different configuration for each or sniffing the platform in application code.
267                 * Detection is the same org.graalvm.nativeimage.imagecode system property check
268                 * every native-image-aware framework uses to avoid a hard dependency on GraalVM's
269                 * own SDK.
270                 */
271                /**
272                 * Picks whichever concrete type actually performs best for the platform this
273                 * process is currently running on, decided once, at appender construction time,
274                 * not re-checked afterward. <strong>Currently</strong> that means
275                 * {@link #SYNCHRONIZED_THREAD_LOCAL_BUFFER} when running as a GraalVM native
276                 * image, or {@link #LOCK_THREAD_LOCAL_BUFFER} otherwise - but that specific
277                 * mapping is an implementation detail of this heuristic, not a contract. The
278                 * whole point of this type is to track whichever choice is actually best, so
279                 * which concrete type a given platform resolves to today may change in a future
280                 * release without notice, as benchmarking improves or platforms evolve.
281                 * <strong>If your deployment needs a specific type to always be used, pick that
282                 * type explicitly instead of relying on what {@code AUTO_DETECT} happens to
283                 * resolve to right now.</strong>
284                 * <p>
285                 * <strong>Not the default</strong> - requires explicitly requesting this type,
286                 * programmatically or via {@link LogAppender#APPENDER_TYPE_PROPERTY}. Downgraded
287                 * the same as an explicit request for whichever type it currently resolves to
288                 * would be: by {@link LogConfig.Globals#appenderLock()} and
289                 * {@link LogConfig.Globals#threadLocal()}.
290                 */
291                AUTO_DETECT;
292
293                static AppenderType parse(String value) {
294                        return LogProperty.enumValue(AppenderType.class, value);
295                }
296
297        }
298
299        /**
300         * Creates a builder.
301         * @param name appender name.
302         * @return builder.
303         */
304        public static Builder builder(String name) {
305                /*
306                 * Eagerly triggers LogProperties' own key-parameter-value validation now,
307                 * matching every annotation-processor-generated Builder's own constructor, which
308                 * does the same via its own eager interpolateKey call: needed because this
309                 * hand-written Builder can otherwise skip every keyed property lookup entirely
310                 * when every field is set explicitly, never validating the name at all. Wrapped
311                 * into a ValidationException the same way a generated builder's constructor is,
312                 * so a bad name reports the same exception type regardless of whether it came
313                 * from logging.appenders (LogAppenderRegistry's own validateNames call) or a
314                 * direct programmatic builder(name) call like this one.
315                 */
316                try {
317                        LogProperties.interpolateNamedKey(LogProperties.APPENDER_PREFIX, name);
318                }
319                catch (IllegalArgumentException e) {
320                        throw LogProperty.ValidationException.of(LogAppender.class, e);
321                }
322                return new Builder(name);
323        }
324
325        /**
326         * Builder for creating standard appenders. Whatever is not set explicitly is resolved
327         * from properties keyed under {@link LogProperties#APPENDER_PREFIX} for this
328         * builder's name (see {@link #fromProperties(LogProperties)}), and failing that from
329         * a small set of defaults: no encoder resolves one from the output's own type, no
330         * flags means none are set, and no appender type means
331         * {@link AppenderType#LOCK_THREAD_LOCAL_BUFFER} - or {@link AppenderType#AUTO_DETECT}
332         * instead, if {@link LogProperties#GLOBAL_OPTIMIZE_PROPERTY} is enabled. There is
333         * deliberately no such default for output, since a required source is not something a
334         * generic named appender can safely guess, except for the well known
335         * {@code "console"}/ {@code "file"} names, which register their own fallback via
336         * {@link #outputDefault(LogProvider)}.
337         */
338        public static final class Builder implements LogBuilder<Builder, LogAppender> {
339
340                private @Nullable LogProvider<? extends LogOutput> output = null;
341
342                /*
343                 * A weaker fallback than an explicit output(...) call: consulted only if neither
344                 * that nor APPENDER_OUTPUT_PROPERTY resolves anything. Package-private, not part
345                 * of the public Builder API: DefaultAppenderRegistry is the only caller, for
346                 * "console"'s stdout default, where the precedence is deliberately the opposite
347                 * of an ordinary explicit value (the property is meant to override this default,
348                 * not the other way around).
349                 */
350                private @Nullable LogProvider<? extends LogOutput> outputDefault = null;
351
352                private @Nullable LogProvider<? extends LogEncoder> encoder = null;
353
354                private @Nullable EnumSet<AppenderFlag> flags = null;
355
356                private @Nullable AppenderType appenderType = null;
357
358                private final String name;
359
360                private Builder(String name) {
361                        this.name = name;
362                }
363
364                Builder outputDefault(LogProvider<? extends LogOutput> outputDefault) {
365                        this.outputDefault = outputDefault;
366                        return this;
367                }
368
369                /**
370                 * Name of the appender.
371                 * @return name.
372                 */
373                public String name() {
374                        return this.name;
375                }
376
377                /**
378                 * Sets output.
379                 * @param output output.
380                 * @return builder.
381                 */
382                public Builder output(LogProvider<? extends LogOutput> output) {
383                        this.output = output;
384                        return this;
385                }
386
387                /**
388                 * Sets output.
389                 * @param output output.
390                 * @return builder.
391                 */
392                public Builder output(LogOutput output) {
393                        this.output = LogProvider.of(output);
394                        return this;
395                }
396
397                /**
398                 * Sets formatter as encoder.
399                 * @param formatter formatter to be converted to encoder.
400                 * @return builder.
401                 * @see LogEncoder#of(LogFormatter)
402                 */
403                public Builder formatter(LogFormatter formatter) {
404                        this.encoder = LogEncoder.of(formatter);
405                        return this;
406                }
407
408                /**
409                 * Sets formatter as encoder.
410                 * @param formatter formatter to be converted to encoder.
411                 * @return builder.
412                 * @see LogEncoder#of(LogFormatter)
413                 */
414                public Builder formatter(LogFormatter.EventFormatter formatter) {
415                        this.encoder = LogEncoder.of(formatter);
416                        return this;
417                }
418
419                /**
420                 * Sets encoder.
421                 * @param encoder encoder not <code>null</code>.
422                 * @return builder.
423                 */
424                public Builder encoder(LogProvider<? extends LogEncoder> encoder) {
425                        this.encoder = encoder;
426                        return this;
427                }
428
429                /**
430                 * Sets encoder.
431                 * @param encoder encoder not <code>null</code>.
432                 * @return builder.
433                 */
434                public Builder encoder(LogEncoder encoder) {
435                        this.encoder = LogProvider.of(encoder);
436                        return this;
437                }
438
439                /**
440                 * Sets appender flags.
441                 * @param flags flags will replace all flags currently set.
442                 * @return this.
443                 */
444                public Builder flags(Collection<AppenderFlag> flags) {
445                        _flags().addAll(flags);
446                        return this;
447                }
448
449                private EnumSet<AppenderFlag> _flags() {
450                        EnumSet<AppenderFlag> flags = this.flags;
451                        if (flags == null) {
452                                this.flags = flags = EnumSet.noneOf(AppenderFlag.class);
453                        }
454                        return flags;
455                }
456
457                /**
458                 * Adds a flag.
459                 * @param flag flag.
460                 * @return this.
461                 */
462                public Builder flag(AppenderFlag flag) {
463                        _flags().add(flag);
464                        return this;
465                }
466
467                /**
468                 * Sets the appender type (buffer/locking strategy). If not set it is resolved
469                 * from {@link LogAppender#APPENDER_TYPE_PROPERTY} or otherwise defaults to
470                 * {@link AppenderType#LOCK_THREAD_LOCAL_BUFFER} ({@link AppenderType#AUTO_DETECT}
471                 * instead if {@link LogProperties#GLOBAL_OPTIMIZE_PROPERTY} is enabled). Calling
472                 * this method always wins over both.
473                 * @param appenderType appender type.
474                 * @return this.
475                 */
476                public Builder appenderType(AppenderType appenderType) {
477                        this.appenderType = appenderType;
478                        return this;
479                }
480
481                @Override
482                public String propertyPrefix() {
483                        return LogProperties.APPENDER_PREFIX;
484                }
485
486                /**
487                 * Fills in whatever of flags/appender type is not already explicitly set on this
488                 * builder from properties keyed under {@link #propertyPrefix()} for this
489                 * builder's name; an already-set field always wins over the property, matching
490                 * every other generated builder's {@code fromProperties} in this project. Both
491                 * are resolved and validated together against one {@link LogProperty.Validator},
492                 * so a builder with both malformed reports both in a single exception rather than
493                 * just the first one reached.
494                 * <p>
495                 * Output/encoder are deliberately not handled here even though they too are keyed
496                 * under {@link #propertyPrefix()}: turning either into a concrete, registered
497                 * {@link LogOutput}/{@link LogEncoder} needs a {@link LogConfig} (to actually
498                 * look up the URI scheme), which this method does not have. {@link #build()}
499                 * resolves those two once a real {@link LogConfig} is available, using the same
500                 * property keys.
501                 * @param properties properties to resolve unset fields from.
502                 * @return this.
503                 */
504                @Override
505                public Builder fromProperties(LogProperties properties) {
506                        /*
507                         * Register every result with the validator first, and only call validate(),
508                         * which throws one aggregate exception up front if anything registered is
509                         * Missing (when added via add(...)) or an Error (either method), before
510                         * extracting any individual value below. Extracting a value via
511                         * value()/valueOrNull() throws immediately for a still-unhandled Error (see
512                         * LogProperty.Result.Error's own valueOrNull()), which would otherwise let
513                         * the first bad property escape unwrapped before the Validator ever got a
514                         * chance to collect the rest: the same ordering the annotation processor
515                         * generates for every other builder in this project.
516                         */
517                        var validator = LogProperty.Validator.of(LogAppender.class);
518                        var flagsResult = flags == null ? properties.forKey(APPENDER_FLAGS_PROPERTY, name)
519                                .ofList()
520                                .map(AppenderFlag::parse)
521                                .validateIfError(validator) : null;
522                        var appenderTypeResult = appenderType == null ? properties.forKey(APPENDER_TYPE_PROPERTY, name)
523                                .ofString()
524                                .map(AppenderType::parse)
525                                .validateIfError(validator) : null;
526                        validator.validate();
527                        if (flagsResult != null) {
528                                var resolved = flagsResult.valueOrNull();
529                                // AppenderFlag.parse always returns an EnumSet (empty or not), so
530                                // EnumSet.copyOf is always safe here, never the "non-EnumSet and empty"
531                                // case it rejects.
532                                if (resolved != null) {
533                                        flags = EnumSet.copyOf(resolved);
534                                }
535                        }
536                        if (appenderTypeResult != null) {
537                                appenderType = appenderTypeResult.valueOrNull();
538                        }
539                        return this;
540                }
541
542                /**
543                 * Builds.
544                 * @return an appender factory.
545                 */
546                public LogProvider<LogAppender> build() {
547                        /*
548                         * We need to capture parameters since appender creation needs to be lazy, and
549                         * a copy is made below (rather than mutating this builder's own fields) so a
550                         * shared/reused Builder instance is never mutated by a later
551                         * fromProperties(...) call the lazy lambda makes once a real LogConfig is
552                         * available.
553                         */
554                        var _name = name;
555                        var _output = output;
556                        var _outputDefault = outputDefault;
557                        var _encoder = encoder;
558                        var _flags = flags;
559                        var _appenderType = appenderType;
560                        /*
561                         * TODO should we use the parent name for resolution?
562                         */
563                        return (n, config) -> {
564                                var b = new Builder(_name);
565                                b.flags = _flags;
566                                b.appenderType = _appenderType;
567                                b.fromProperties(config.properties());
568
569                                LogOutput output = LogProvider.provideOrNull(_output, _name, config);
570                                if (output == null) {
571                                        /*
572                                         * A malformed (not just missing) property must throw here,
573                                         * immediately, regardless of whether a default exists below: e.g.
574                                         * "console" with a genuinely bad logging.appender.console.output.uri
575                                         * must fail loudly, not silently fall back to stdout. Only the
576                                         * Missing case falls through to outputDefault.
577                                         */
578                                        output = switch (outputProperty(_name, config)) {
579                                                case LogProperty.Result.Success<LogOutput> s -> s.value();
580                                                case LogProperty.Result.Missing<LogOutput> m -> null;
581                                                case LogProperty.Result.Error<LogOutput> e -> e.value();
582                                        };
583                                }
584                                if (output == null) {
585                                        output = LogProvider.provideOrNull(_outputDefault, _name, config);
586                                }
587                                if (output == null) {
588                                        /*
589                                         * No explicit value, no property, no default: the same missing
590                                         * -property failure a required property with no fallback produces
591                                         * anywhere else. Re-deriving the same (definitely still Missing)
592                                         * result and calling value() throws it unwrapped, no Validator
593                                         * involved, same as before this refactor.
594                                         */
595                                        output = DefaultAppenderRegistry.rawValue(outputProperty(_name, config)).value();
596                                }
597
598                                try {
599                                        return build(b, _name, output, _encoder, config);
600                                }
601                                catch (RuntimeException | Error e) {
602                                        /*
603                                         * The appender would have owned the output, so nothing else will
604                                         * close it, and an open file cannot be deleted on Windows.
605                                         */
606                                        closeAfterFailure(output, e);
607                                        throw e;
608                                }
609                        };
610                }
611
612                private static LogAppender build(Builder b, String name, LogOutput output,
613                                @Nullable LogProvider<? extends LogEncoder> encoderProvider, LogConfig config) {
614                        LogEncoder explicitEncoder = encoderProvider != null
615                                        ? LogProvider.provideOrNull(encoderProvider, name, config) : null;
616                        LogEncoder encoder;
617                        if (output instanceof LogOutput.ProvidesEncoder pe
618                                        && pe.policy() == LogOutput.ProvidesEncoder.Policy.MANDATORY) {
619                                boolean propertyWired = !(encoderProperty(name, config) instanceof LogProperty.Result.Missing);
620                                if (explicitEncoder != null || propertyWired) {
621                                        throw LogProperty.ValidationException
622                                                .of(LogAppender.class, new IllegalArgumentException("Appender '" + name + "' output "
623                                                                + output.getClass().getName()
624                                                                + " provides a mandatory encoder and does not allow another encoder to be configured."));
625                                }
626                                encoder = pe.encoder(name, config);
627                        }
628                        else {
629                                encoder = explicitEncoder;
630                                if (encoder == null) {
631                                        var propertyResult = encoderProperty(name, config);
632                                        if (output instanceof LogOutput.ProvidesEncoder pe
633                                                        && propertyResult instanceof LogProperty.Result.Missing) {
634                                                encoder = pe.encoder(name, config);
635                                        }
636                                        else {
637                                                encoder = DefaultAppenderRegistry.rawValue(propertyResult.or(() -> config.encoderRegistry()
638                                                        .encoderForOutputType(output.type())
639                                                        .provide(name, config))).value();
640                                        }
641                                }
642                        }
643
644                        Set<AppenderFlag> flags = b.flags != null ? b.flags : EnumSet.noneOf(AppenderFlag.class);
645                        AppenderType appenderType = b.appenderType != null ? b.appenderType
646                                        : config.globals().optimize() ? AppenderType.AUTO_DETECT : AppenderType.LOCK_THREAD_LOCAL_BUFFER;
647
648                        return DirectLogAppender.of(name, output, encoder, appenderType, flags, config);
649                }
650
651                @SuppressWarnings("ReferenceEquality") // Self-suppression is based on identity.
652                static void closeAfterFailure(AutoCloseable resource, Throwable failure) {
653                        try {
654                                resource.close();
655                        }
656                        catch (Exception | Error e) {
657                                if (e != failure) {
658                                        failure.addSuppressed(e);
659                                }
660                        }
661                }
662
663                /*
664                 * Resolves APPENDER_OUTPUT_PROPERTY all the way to a concrete LogOutput (not just
665                 * a LogProvider), via LogProperty.provideValue so a failure inside the provided
666                 * LogOutput's own construction (its own separate property tree, e.g.
667                 * logging.appender.file.output.file.bufferSize) is not relabeled
668                 * "Error converting property" as if APPENDER_OUTPUT_PROPERTY's own value had
669                 * failed to convert - see LogProperty#providingError. Moved here since output
670                 * resolution is now entirely this Builder's concern.
671                 */
672                private static LogProperty.Result<LogOutput> outputProperty(String name, LogConfig config) {
673                        return LogProperty.provideValue(
674                                        config.properties().forKey(APPENDER_OUTPUT_PROPERTY, name).ofProvider(LogOutput::of), name, config);
675                }
676
677                private static LogProperty.Result<LogEncoder> encoderProperty(String name, LogConfig config) {
678                        return LogProperty.provideValue(
679                                        config.properties().forKey(APPENDER_ENCODER_PROPERTY, name).ofProvider(LogEncoder::of), name,
680                                        config);
681                }
682
683        }
684
685        /**
686         * Provides appenders safely to the publisher. The providing calls of
687         * <code>asXXX</code> can only be called once as they register the appenders.
688         */
689        final class Appenders {
690
691                private final AtomicBoolean created = new AtomicBoolean();
692
693                private final String name;
694
695                private final LogConfig config;
696
697                private final List<LogProvider<LogAppender>> appenders;
698
699                /*
700                 * Set once, inside asList()/asSingle(), so LogReporter can find out what a
701                 * publisher was actually given without asking the publisher itself (which would
702                 * mean every current and future publisher implementation cooperating): see
703                 * resolvedOrNull(). Not re-derivable by calling asList()/asSingle() again: both
704                 * are one-shot (see the created guard above).
705                 */
706                private @Nullable List<? extends LogAppender> resolved;
707
708                Appenders(String name, LogConfig config, List<LogProvider<LogAppender>> appenders) {
709                        super();
710                        this.name = name;
711                        this.config = config;
712                        this.appenders = appenders;
713                }
714
715                /**
716                 * Return the appenders as a list.
717                 * @return list of appenders.
718                 * @throws IllegalStateException if appenders are already registered.
719                 */
720                public List<? extends LogAppender> asList() throws IllegalStateException {
721                        if (created.compareAndSet(false, true)) {
722                                var apps = appenders();
723                                List<LogAppender> appenders = new ArrayList<>();
724                                for (var a : apps) {
725                                        appenders.add(register(a));
726                                }
727                                resolved = appenders;
728                                return appenders;
729                        }
730                        else {
731                                throw new IllegalStateException("Appenders already provided.");
732                        }
733
734                }
735
736                /**
737                 * Consolidate the appenders as a single appender, appended synchronously. If more
738                 * than one appender is combined, each keeps its own independent lock and is
739                 * appended to directly - see {@link CompositeLogAppender}.
740                 * @return single appender.
741                 * @throws IllegalStateException if appenders are already registered.
742                 */
743                public LogAppender asSingle() throws IllegalStateException {
744                        if (created.compareAndSet(false, true)) {
745                                var apps = appenders();
746                                var appender = composite(apps);
747                                resolved = List.of(appender);
748                                return register(appender);
749                        }
750                        else {
751                                throw new IllegalStateException("Appenders already provided.");
752                        }
753                }
754
755                /**
756                 * The appenders actually resolved by whichever of {@link #asList()}/
757                 * {@link #asSingle()} a publisher factory called, or <code>null</code> if neither
758                 * has been called yet (a publisher factory that never calls either one has no
759                 * real appenders to report on regardless).
760                 * @return resolved appenders, or <code>null</code>.
761                 */
762                @Nullable List<? extends LogAppender> resolvedOrNull() {
763                        return resolved;
764                }
765
766                private LogAppender register(LogAppender appender) {
767                        return switch (appender) {
768                                case DirectLogAppender ia -> {
769                                        config.serviceRegistry().put(LogAppender.class, name + "." + ia.name(), ia);
770                                        yield ia;
771                                }
772                                case CompositeLogAppender ca -> {
773                                        config.serviceRegistry().put(LogAppender.class, name, ca);
774                                        yield ca;
775                                }
776                                default -> {
777                                        throw new IllegalStateException();
778                                }
779                        };
780                }
781
782                private List<LogAppender> appenders() {
783                        LogProvider<List<LogAppender>> all = (n, c) -> {
784                                List<LogAppender> list = new ArrayList<>();
785                                try {
786                                        for (var p : appenders) {
787                                                list.add(p.provide(n, c));
788                                        }
789                                }
790                                catch (RuntimeException | Error e) {
791                                        /*
792                                         * The route never gets the appenders already made, so close their
793                                         * outputs.
794                                         */
795                                        for (var a : list) {
796                                                Builder.closeAfterFailure(a, e);
797                                        }
798                                        throw e;
799                                }
800                                return list;
801                        };
802                        return all.describe(n -> "Appenders for route: '" + n + "'").provide(name, config);
803                }
804
805                /**
806                 * Creates a composite log appender from many, each keeping its own independent
807                 * lock.
808                 * @param appenders appenders.
809                 * @return appender.
810                 */
811                private static LogAppender composite(List<? extends LogAppender> appenders) {
812                        if (appenders.isEmpty()) {
813                                throw new IllegalArgumentException("A single appender is required");
814                        }
815                        if (appenders.size() == 1) {
816                                return Objects.requireNonNull(appenders.get(0));
817                        }
818                        return CompositeLogAppender.of(appenders);
819                }
820
821        }
822
823        @Override
824        public void close();
825
826}
827
828interface AppenderVisitor {
829
830        boolean consume(DirectLogAppender appender);
831
832}
833
834/**
835 * This is a JAVADOC BUG
836 */
837sealed interface InternalLogAppender extends LogAppender, Actor {
838
839        static InternalLogAppender of(LogAppender appender) {
840                return Objects.requireNonNull((InternalLogAppender) appender); // TODO eclipse
841                                                                                                                                                // bug.
842        }
843
844        /**
845         * An appender can act on actions. One of the key actions is reopening files.
846         * @param action action to run.
847         * @return alert events for anything that failed, empty if the action fully succeeded.
848         */
849        @Override
850        public List<LogEvent> act(LogAction action);
851
852        /**
853         * Removes the current thread's thread local state, if any. Unlike {@link #act} this
854         * takes no lock since only the calling thread's state is touched.
855         */
856        default void clearThreadLocals() {
857        }
858
859}
860
861sealed interface DirectLogAppender extends InternalLogAppender {
862
863        String name();
864
865        LogOutput output();
866
867        LogEncoder encoder();
868
869        default List<LogEvent> _request(LogAction action) {
870                return switch (action) {
871                        case LogAction.StandardAction a -> switch (a) {
872                                case LogAction.StandardAction.REOPEN -> reopen();
873                                case LogAction.StandardAction.FLUSH -> flush();
874                        };
875                };
876        }
877
878        /**
879         * Reopens {@link #output()}. Any failure is reported to the alert system rather than
880         * thrown, at {@link Level#ERROR}.
881         * @return the alert event if reopening failed, empty if it succeeded.
882         */
883        List<LogEvent> reopen();
884
885        /**
886         * Flushes {@link #output()}. Any failure is reported to the alert system rather than
887         * thrown, at {@link Level#ERROR}.
888         * @return the alert event if flushing failed, empty if it succeeded.
889         */
890        List<LogEvent> flush();
891
892        static DirectLogAppender of(String name, LogOutput output, LogEncoder encoder, AppenderType type,
893                        Set<LogAppender.AppenderFlag> flags, LogConfig config) {
894                var alerts = config.alerts();
895                var metrics = config.metrics();
896                var globals = config.globals();
897                type = AbstractLogAppender.resolveAutoDetectAppenderType(type);
898                type = AbstractLogAppender.applyAppenderLock(type, globals.appenderLock(), Runtime.version().feature());
899                type = AbstractLogAppender.guardThreadLocalAppenderType(type,
900                                globals.threadLocal() == LogConfig.Globals.ThreadLocalMode.FORBID);
901                return switch (type) {
902                        case REUSE_BUFFER ->
903                                new ReuseBufferLogAppender(name, output, encoder, flags, new ReentrantLock(), alerts, metrics);
904                        case SYNCHRONIZED_THREAD_LOCAL_BUFFER ->
905                                new SynchronizedThreadLocalBufferLogAppender(name, output, encoder, flags, alerts, metrics);
906                        case LOCK_THREAD_LOCAL_BUFFER -> new LockThreadLocalBufferLogAppender(name, output, encoder, flags,
907                                        new ReentrantLock(), alerts, metrics);
908                        case LOCK_NEW_BUFFER ->
909                                new LockNewBufferLogAppender(name, output, encoder, flags, new ReentrantLock(), alerts, metrics);
910                        case AUTO_DETECT ->
911                                throw new IllegalStateException("AUTO_DETECT should have already been resolved to a concrete type");
912                };
913        }
914
915}
916
917/**
918 * An abstract appender to help create custom appenders.
919 */
920sealed abstract class AbstractLogAppender implements DirectLogAppender {
921
922        /**
923         * Applies {@link LogConfig.Globals#appenderLock()} to a resolved appender type, the
924         * enforcement point that makes the lock a guarantee rather than a changed default.
925         * Only the thread local buffer types have both a reentrant lock and a
926         * {@code synchronized} variant; other types are returned unchanged.
927         * @param type resolved appender type.
928         * @param lock appender lock.
929         * @param jdkFeature the running JDK's feature version, which decides
930         * {@link LogConfig.Globals.AppenderLock#AUTO}.
931         * @return the appender type to use.
932         */
933        static LogAppender.AppenderType applyAppenderLock(LogAppender.AppenderType type,
934                        LogConfig.Globals.AppenderLock lock, int jdkFeature) {
935                var effective = lock == LogConfig.Globals.AppenderLock.AUTO && jdkFeature < 24
936                                ? LogConfig.Globals.AppenderLock.REENTRANT : lock;
937                return switch (effective) {
938                        case AUTO -> type;
939                        case REENTRANT -> type == LogAppender.AppenderType.SYNCHRONIZED_THREAD_LOCAL_BUFFER
940                                        ? LogAppender.AppenderType.LOCK_THREAD_LOCAL_BUFFER : type;
941                        case SYNCHRONIZED -> type == LogAppender.AppenderType.LOCK_THREAD_LOCAL_BUFFER
942                                        ? LogAppender.AppenderType.SYNCHRONIZED_THREAD_LOCAL_BUFFER : type;
943                };
944        }
945
946        /**
947         * Downgrades either {@link ThreadLocal}-backed type (
948         * {@link LogAppender.AppenderType#LOCK_THREAD_LOCAL_BUFFER} or
949         * {@link LogAppender.AppenderType#SYNCHRONIZED_THREAD_LOCAL_BUFFER}) to
950         * {@link LogAppender.AppenderType#LOCK_NEW_BUFFER} if {@code forbid} is true - the
951         * enforcement point that makes the global no-{@link ThreadLocal} guarantee a real
952         * guarantee rather than just a changed default. An explicit
953         * {@link LogAppender.AppenderType#REUSE_BUFFER} request is left as-is - it is already
954         * {@link ThreadLocal}-free, so there is nothing to downgrade.
955         * @param type type as given to an appender factory method.
956         * @param forbid whether {@link LogConfig.Globals#threadLocal()} is
957         * {@link LogConfig.Globals.ThreadLocalMode#FORBID}.
958         * @return {@code type} unchanged, unless the guarantee is active and a
959         * {@link ThreadLocal}-backed type was requested, in which case
960         * {@code LOCK_NEW_BUFFER} instead.
961         */
962        static LogAppender.AppenderType guardThreadLocalAppenderType(LogAppender.AppenderType type, boolean forbid) {
963                if (!forbid) {
964                        return type;
965                }
966                return switch (type) {
967                        case LOCK_THREAD_LOCAL_BUFFER, SYNCHRONIZED_THREAD_LOCAL_BUFFER -> LogAppender.AppenderType.LOCK_NEW_BUFFER;
968                        case REUSE_BUFFER, LOCK_NEW_BUFFER -> type;
969                        case AUTO_DETECT ->
970                                throw new IllegalStateException("AUTO_DETECT should have already been resolved to a concrete type");
971                };
972        }
973
974        /**
975         * Resolves {@link LogAppender.AppenderType#AUTO_DETECT} to
976         * {@link LogAppender.AppenderType#SYNCHRONIZED_THREAD_LOCAL_BUFFER} or
977         * {@link LogAppender.AppenderType#LOCK_THREAD_LOCAL_BUFFER} depending on
978         * {@link #isNativeImageRuntime()}; any other type is returned unchanged. Called
979         * before
980         * {@link #applyAppenderLock(LogAppender.AppenderType, LogConfig.Globals.AppenderLock, int)}
981         * and {@link #guardThreadLocalAppenderType(LogAppender.AppenderType, boolean)} so a
982         * resolved {@code SYNCHRONIZED_THREAD_LOCAL_BUFFER} is still subject to both of those
983         * global guarantees the same as if it had been requested directly.
984         * @param type type as given to an appender factory method.
985         * @return {@code type} unchanged unless it was {@code AUTO_DETECT}.
986         */
987        static LogAppender.AppenderType resolveAutoDetectAppenderType(LogAppender.AppenderType type) {
988                if (type != LogAppender.AppenderType.AUTO_DETECT) {
989                        return type;
990                }
991                return isNativeImageRuntime() ? LogAppender.AppenderType.SYNCHRONIZED_THREAD_LOCAL_BUFFER
992                                : LogAppender.AppenderType.LOCK_THREAD_LOCAL_BUFFER;
993        }
994
995        /**
996         * The system property GraalVM native-image itself sets to {@code buildtime} during
997         * the image build and {@code runtime} when the built image actually executes - absent
998         * entirely on a plain JVM. The standard, dependency-free way every native-image-aware
999         * framework checks "am I native" without a hard compile-time dependency on GraalVM's
1000         * own SDK just to ask this one question.
1001         */
1002        static final String NATIVE_IMAGE_CODE_PROPERTY = "org.graalvm.nativeimage.imagecode";
1003
1004        /**
1005         * Whether this process is currently running as an executing (not building) GraalVM
1006         * native image - see {@link #NATIVE_IMAGE_CODE_PROPERTY}.
1007         * @return true if running as a native image at runtime.
1008         */
1009        static boolean isNativeImageRuntime() {
1010                return "runtime".equals(System.getProperty(NATIVE_IMAGE_CODE_PROPERTY));
1011        }
1012
1013        /**
1014         * Records a failed append: always counted, alerted only when it starts an episode of
1015         * failures.
1016         * <p>
1017         * An Error is a failure like any other, because event data can raise one while it is
1018         * encoded, for example a throwable whose getMessage() overflows the stack. Letting it
1019         * escape would throw it at the caller of a synchronous route and stop the worker of
1020         * an asynchronous one for good. Only an error that leaves the JVM unusable is
1021         * rethrown.
1022         * @param e the failure.
1023         * @param count events that failed to append.
1024         * @param batch whether they were appended as a batch.
1025         */
1026        final void appendFailed(Throwable e, int count, boolean batch) {
1027                if (e instanceof VirtualMachineError fatal && !(e instanceof StackOverflowError)) {
1028                        throw fatal;
1029                }
1030                metrics.errorCounter(LogMetrics.EVENTS_FAILED_METRIC, count);
1031                long previous = failureCount.getAndUpdate(value -> value < 0 ? 0 : value + count);
1032                if (previous < 0) {
1033                        alerts.error(getClass(), batch ? "appender '" + name + "' failed to append batch of " + count + " event(s)"
1034                                        : "appender '" + name + "' failed to append event", e);
1035                }
1036        }
1037
1038        /**
1039         * Ends an episode of failures, if one is under way, with one warning saying how many
1040         * further events failed without being reported.
1041         */
1042        final void appendSucceeded() {
1043                if (failureCount.get() < 0) {
1044                        return;
1045                }
1046                long count = failureCount.getAndSet(-1);
1047                if (count >= 0) {
1048                        alerts.warn(getClass(), "appender '" + name + "' recovered; " + count
1049                                        + " more event(s) failed to append after the reported failure");
1050                }
1051        }
1052
1053        /**
1054         * Whether an appender should drop (or drop-and-log) an append call because it is
1055         * reentrant - i.e. the current thread is already inside a previous call to the same
1056         * appender, which happens if an output does logging itself during its own write or an
1057         * argument's {@code toString()} logs while the event is encoded. Shared by every
1058         * appender that can detect reentrancy, regardless of whether it does so via a
1059         * {@link ReentrantLock} ( {@code lock.isHeldByCurrentThread()}) or a
1060         * {@code synchronized} block ( {@link Thread#holdsLock(Object)}) - callers pass in
1061         * whichever check applies to them. Whenever this returns {@code true},
1062         * {@link LogMetrics#EVENTS_DROPPED_METRIC} is incremented by {@code count} regardless
1063         * of whether {@link AppenderFlag#REENTRY_LOG} is set - counting and logging/alerting
1064         * are separate concerns, so the count still happens even when the drop itself is
1065         * silent.
1066         * @param reentrant whether the current thread already holds this appender's
1067         * lock/monitor or is using its thread's buffer.
1068         * @param flags the appender's flags.
1069         * @param metrics where to record {@link LogMetrics#EVENTS_DROPPED_METRIC} if events
1070         * are dropped.
1071         * @param count number of events that would be dropped - {@code 1} for a single event
1072         * append, or the batch size for a batch append.
1073         * @return {@code true} if the caller should drop the event(s) without appending.
1074         */
1075        static boolean shouldDropForReentry(boolean reentrant, Set<LogAppender.AppenderFlag> flags, LogMetrics metrics,
1076                        int count) {
1077                if (!reentrant) {
1078                        return false;
1079                }
1080                if (flags.contains(LogAppender.AppenderFlag.REENTRY_LOG)) {
1081                        Exception exception = new Exception("reentrant appender");
1082                        MetaLog.error(LogAppender.class, exception);
1083                        metrics.errorCounter(LogMetrics.EVENTS_DROPPED_METRIC, count);
1084                        return true;
1085                }
1086                if (flags.contains(LogAppender.AppenderFlag.REENTRY_DROP)) {
1087                        metrics.errorCounter(LogMetrics.EVENTS_DROPPED_METRIC, count);
1088                        return true;
1089                }
1090                return false;
1091        }
1092
1093        /**
1094         * name.
1095         */
1096        protected final String name;
1097
1098        /**
1099         * output
1100         */
1101        protected final LogOutput output;
1102
1103        /**
1104         * encoder
1105         */
1106        protected final LogEncoder encoder;
1107
1108        protected final Set<LogAppender.AppenderFlag> flags;
1109
1110        protected final boolean immediateFlush;
1111
1112        /**
1113         * alerts for reporting encode/write failures that this appender catches so they never
1114         * propagate back to whatever application thread called logger.info(...).
1115         */
1116        protected final LogAlerts alerts;
1117
1118        /**
1119         * metrics for recording counters like {@link LogMetrics#EVENTS_DROPPED_METRIC}.
1120         */
1121        protected final LogMetrics metrics;
1122
1123        /*
1124         * A failing output usually fails every append until something outside the process
1125         * changes, so only the first failure of an episode is alerted: printing one stack
1126         * trace per log call only widens the damage. Every failure is still counted.
1127         */
1128        // Negative means healthy; otherwise count failures after the first alert.
1129        private final AtomicLong failureCount = new AtomicLong(-1);
1130
1131        /**
1132         * Creates an appender from an output and encoder.
1133         * @param output set the output field and will be started and closed with the
1134         * appender.
1135         * @param encoder set the encoder field.
1136         * @param alerts alerts for reporting encode/write failures.
1137         * @param metrics metrics for recording counters.
1138         */
1139        protected AbstractLogAppender(String name, LogOutput output, LogEncoder encoder,
1140                        Set<LogAppender.AppenderFlag> flags, LogAlerts alerts, LogMetrics metrics) {
1141                super();
1142                this.name = name;
1143                this.output = output;
1144                this.encoder = encoder;
1145                this.flags = flags;
1146                this.immediateFlush = !flags.contains(LogAppender.AppenderFlag.DISABLE_IMMEDIATE_FLUSH);
1147                this.alerts = alerts;
1148                this.metrics = metrics;
1149        }
1150
1151        @Override
1152        public void start(LogConfig config) {
1153                output.start(config);
1154        }
1155
1156        @Override
1157        public void close() {
1158                output.close();
1159        }
1160
1161        @Override
1162        public String toString() {
1163                return getClass().getName() + "[name=" + name + " encoder=" + encoder + ", " + "output=" + output + ", flags="
1164                                + flags + "]";
1165        }
1166
1167        @Override
1168        public String name() {
1169                return this.name;
1170        }
1171
1172        @Override
1173        public LogOutput output() {
1174                return this.output;
1175        }
1176
1177        @Override
1178        public LogEncoder encoder() {
1179                return this.encoder;
1180        }
1181
1182        @Override
1183        public List<LogEvent> reopen() {
1184                metrics.infoCounter(LogMetrics.REOPEN_METRIC, 1);
1185                try {
1186                        output.reopen();
1187                        return List.of();
1188                }
1189                catch (Exception e) {
1190                        metrics.errorCounter(LogMetrics.REOPEN_FAIL_METRIC, 1);
1191                        var event = errorEvent(getClass(), "appender '" + name + "' failed to reopen output", e);
1192                        alerts.alert(event);
1193                        return List.of(event);
1194                }
1195        }
1196
1197        @Override
1198        public List<LogEvent> flush() {
1199                try {
1200                        output.flush();
1201                        return List.of();
1202                }
1203                catch (Exception e) {
1204                        var event = errorEvent(getClass(), "appender '" + name + "' failed to flush output", e);
1205                        alerts.alert(event);
1206                        return List.of(event);
1207                }
1208        }
1209
1210        private static LogEvent errorEvent(Class<?> loggerName, String message, Throwable throwable) {
1211                var currentThread = Thread.currentThread();
1212                return LogEvent.of(Instant.now(), currentThread.getName(), currentThread.threadId(), Level.ERROR,
1213                                loggerName.getName(), message, KeyValues.of(), throwable);
1214        }
1215
1216}
1217
1218/**
1219 * Combines more than one appender on a route into one {@link LogAppender}. Each appender
1220 * keeps the independent lock it was already constructed with, and
1221 * {@link #append(LogEvent)}/{@link #append(LogEvent[], int)} skip locking at the
1222 * composite level entirely and append to every component directly - so e.g. a console
1223 * appender and a file appender under the same route never contend on the same lock for
1224 * unrelated I/O. {@link #start(LogConfig)}/{@link #close()}/{@link #act(LogAction)} do
1225 * the same - there is no composite-owned mutable state to protect, only a loop over
1226 * components that already handle their own synchronization where it matters.
1227 */
1228@SuppressWarnings("ArrayRecordComponent")
1229record CompositeLogAppender(DirectLogAppender[] appenders) implements InternalLogAppender {
1230
1231        public static CompositeLogAppender of(List<? extends LogAppender> appenders) {
1232                @SuppressWarnings("null") // TODO Eclipse issue here
1233                DirectLogAppender @NonNull [] array = appenders.stream()
1234                        .map(CompositeLogAppender::cast)
1235                        .toArray(i -> new DirectLogAppender[i]);
1236                return new CompositeLogAppender(array);
1237        }
1238
1239        private static DirectLogAppender cast(LogAppender appender) {
1240                return (DirectLogAppender) appender;
1241        }
1242
1243        @Override
1244        public void append(LogEvent event) {
1245                for (var appender : appenders) {
1246                        appender.append(event);
1247                }
1248        }
1249
1250        @Override
1251        public void append(LogEvent[] event, int count) {
1252                for (var appender : appenders) {
1253                        appender.append(event, count);
1254                }
1255        }
1256
1257        @Override
1258        public void close() {
1259                for (var appender : appenders) {
1260                        appender.close();
1261                }
1262        }
1263
1264        @Override
1265        public void start(LogConfig config) {
1266                for (var appender : appenders) {
1267                        appender.start(config);
1268                }
1269        }
1270
1271        @Override
1272        public List<LogEvent> act(LogAction action) {
1273                return Actor.act(appenders, action);
1274        }
1275
1276        @Override
1277        public void clearThreadLocals() {
1278                for (var appender : appenders) {
1279                        appender.clearThreadLocals();
1280                }
1281        }
1282
1283        @Override
1284        public String toString() {
1285                return getClass().getName() + "[appenders=" + Arrays.toString(appenders) + "]";
1286        }
1287
1288}
1289
1290sealed abstract class LockLogAppender extends AbstractLogAppender implements InternalLogAppender {
1291
1292        protected final ReentrantLock lock;
1293
1294        public LockLogAppender(String name, LogOutput output, LogEncoder encoder, Set<LogAppender.AppenderFlag> flags,
1295                        ReentrantLock lock, LogAlerts alerts, LogMetrics metrics) {
1296                super(name, output, encoder, flags, alerts, metrics);
1297                this.lock = lock;
1298        }
1299
1300        @Override
1301        public List<LogEvent> act(LogAction action) {
1302                lock.lock();
1303                try {
1304                        return _request(action);
1305                }
1306                finally {
1307                        lock.unlock();
1308                }
1309        }
1310
1311        @Override
1312        public void close() {
1313                lock.lock();
1314                try {
1315                        super.close();
1316                }
1317                finally {
1318                        lock.unlock();
1319                }
1320        }
1321
1322}
1323
1324/*
1325 * The idea here is to reuse the buffer trading lock contention for less GC.
1326 */
1327final class ReuseBufferLogAppender extends LockLogAppender implements InternalLogAppender {
1328
1329        private final LogEncoder.Buffer buffer;
1330
1331        ReuseBufferLogAppender(String name, LogOutput output, LogEncoder encoder, Set<LogAppender.AppenderFlag> flags,
1332                        ReentrantLock lock, LogAlerts alerts, LogMetrics metrics) {
1333                super(name, output, encoder, flags, lock, alerts, metrics);
1334                this.buffer = encoder.buffer(output.bufferHints());
1335        }
1336
1337        @Override
1338        public final void append(LogEvent event) {
1339                boolean reentrant = lock.isHeldByCurrentThread();
1340                if (shouldDropForReentry(reentrant, flags, metrics, 1)) {
1341                        return;
1342                }
1343                try {
1344                        lock.lock();
1345                        try {
1346                                // A reentrant call must not clear the buffer the outer event is in.
1347                                var buffer = reentrant ? encoder.buffer(output.bufferHints()) : this.buffer;
1348                                buffer.clear();
1349                                encoder.encode(event, buffer);
1350                                output.write(event, buffer);
1351                                if (immediateFlush) {
1352                                        output.flush();
1353                                }
1354                        }
1355                        finally {
1356                                lock.unlock();
1357                        }
1358                        appendSucceeded();
1359                }
1360                catch (Throwable e) {
1361                        appendFailed(e, 1, false);
1362                }
1363        }
1364
1365        @Override
1366        public void append(LogEvent[] events, int count) {
1367                boolean reentrant = lock.isHeldByCurrentThread();
1368                if (shouldDropForReentry(reentrant, flags, metrics, count)) {
1369                        return;
1370                }
1371                try {
1372                        lock.lock();
1373                        try {
1374                                output.write(events, count, encoder, reentrant ? encoder.buffer(output.bufferHints()) : this.buffer);
1375                                if (immediateFlush) {
1376                                        output.flush();
1377                                }
1378                        }
1379                        finally {
1380                                lock.unlock();
1381                        }
1382                        if (count > 0) {
1383                                appendSucceeded();
1384                        }
1385                }
1386                catch (Throwable e) {
1387                        appendFailed(e, count, true);
1388                }
1389        }
1390
1391        @Override
1392        public void close() {
1393                lock.lock();
1394                try {
1395                        super.close();
1396                        buffer.close();
1397                }
1398                finally {
1399                        lock.unlock();
1400                }
1401        }
1402
1403}
1404
1405/*
1406 * The idea here is to encode outside the lock. Instead of allocating a fresh buffer per
1407 * event or sharing (and thus serializing access to) a single buffer
1408 * (ReuseBufferLogAppender), each thread gets its own buffer that only it will ever touch,
1409 * so encoding never needs to be guarded by the lock at all - only the final write to the
1410 * output does.
1411 */
1412final class LockThreadLocalBufferLogAppender extends LockLogAppender implements InternalLogAppender {
1413
1414        /*
1415         * There is no way to enumerate every thread's buffer to close it on appender close so
1416         * we rely on Buffer implementations not holding onto real resources (today they are
1417         * all just wrapped in-memory builders) and let the ThreadLocal itself (and
1418         * consequently the per-thread entries) become collectible once this appender is
1419         * discarded.
1420         */
1421        // CheckerFramework's ThreadLocal stub declares T as inherently @Nullable since get()
1422        // can return null before initialValue() runs, but withInitial(...) below guarantees
1423        // it never does here.
1424        @SuppressWarnings("nullness:type.argument")
1425        private final ThreadLocal<ThreadBuffer> bufferThreadLocal;
1426
1427        LockThreadLocalBufferLogAppender(String name, LogOutput output, LogEncoder encoder,
1428                        Set<LogAppender.AppenderFlag> flags, ReentrantLock lock, LogAlerts alerts, LogMetrics metrics) {
1429                super(name, output, encoder, flags, lock, alerts, metrics);
1430                this.bufferThreadLocal = ThreadLocal.withInitial(() -> new ThreadBuffer(encoder.buffer(output.bufferHints())));
1431        }
1432
1433        @Override
1434        public void clearThreadLocals() {
1435                bufferThreadLocal.remove();
1436        }
1437
1438        @Override
1439        public final void append(LogEvent event) {
1440                try {
1441                        var local = bufferThreadLocal.get();
1442                        /*
1443                         * Encoding is outside the lock, so the lock alone misses a log call made
1444                         * while this thread encodes, such as from an argument's toString().
1445                         */
1446                        boolean reentrant = local.inUse || lock.isHeldByCurrentThread();
1447                        if (shouldDropForReentry(reentrant, flags, metrics, 1)) {
1448                                return;
1449                        }
1450                        try {
1451                                var buffer = reentrant ? encoder.buffer(output.bufferHints()) : local.acquire();
1452                                encoder.encode(event, buffer);
1453                                writeLocked(event, buffer);
1454                        }
1455                        finally {
1456                                if (!reentrant) {
1457                                        local.inUse = false;
1458                                }
1459                        }
1460                        appendSucceeded();
1461                }
1462                catch (Throwable e) {
1463                        appendFailed(e, 1, false);
1464                }
1465        }
1466
1467        private void writeLocked(LogEvent event, LogEncoder.Buffer buffer) {
1468                lock.lock();
1469                try {
1470                        output.write(event, buffer);
1471                        if (immediateFlush) {
1472                                output.flush();
1473                        }
1474                }
1475                finally {
1476                        lock.unlock();
1477                }
1478        }
1479
1480        @Override
1481        public void append(LogEvent[] events, int count) {
1482                try {
1483                        var local = bufferThreadLocal.get();
1484                        boolean reentrant = local.inUse || lock.isHeldByCurrentThread();
1485                        if (shouldDropForReentry(reentrant, flags, metrics, count)) {
1486                                return;
1487                        }
1488                        try {
1489                                var buffer = reentrant ? encoder.buffer(output.bufferHints()) : local.acquire();
1490                                lock.lock();
1491                                try {
1492                                        output.write(events, count, encoder, buffer);
1493                                        if (immediateFlush) {
1494                                                output.flush();
1495                                        }
1496                                }
1497                                finally {
1498                                        lock.unlock();
1499                                }
1500                        }
1501                        finally {
1502                                if (!reentrant) {
1503                                        local.inUse = false;
1504                                }
1505                        }
1506                        if (count > 0) {
1507                                appendSucceeded();
1508                        }
1509                }
1510                catch (Throwable e) {
1511                        appendFailed(e, count, true);
1512                }
1513        }
1514
1515}
1516
1517/*
1518 * A thread's reusable buffer for the thread local buffer appenders. inUse marks that the
1519 * thread is encoding or writing an event with it, so a log call made meanwhile gets a
1520 * fresh buffer instead of clearing this one.
1521 */
1522final class ThreadBuffer {
1523
1524        final LogEncoder.Buffer buffer;
1525
1526        boolean inUse;
1527
1528        ThreadBuffer(LogEncoder.Buffer buffer) {
1529                this.buffer = buffer;
1530        }
1531
1532        LogEncoder.Buffer acquire() {
1533                inUse = true;
1534                buffer.clear();
1535                return buffer;
1536        }
1537
1538}
1539
1540/*
1541 * Like LockThreadLocalBufferLogAppender (encode outside the lock, lock only the final
1542 * write) except the buffer is a fresh allocation per event instead of a ThreadLocal - for
1543 * deployments that want a hard guarantee of no ThreadLocal anywhere in the logging path
1544 * without paying ReuseBufferLogAppender's lock-across-the-whole-encode cost.
1545 */
1546final class LockNewBufferLogAppender extends LockLogAppender implements InternalLogAppender {
1547
1548        LockNewBufferLogAppender(String name, LogOutput output, LogEncoder encoder, Set<LogAppender.AppenderFlag> flags,
1549                        ReentrantLock lock, LogAlerts alerts, LogMetrics metrics) {
1550                super(name, output, encoder, flags, lock, alerts, metrics);
1551        }
1552
1553        @Override
1554        public final void append(LogEvent event) {
1555                try {
1556                        var buffer = encoder.buffer(output.bufferHints());
1557                        encoder.encode(event, buffer);
1558                        if (writeLocked(event, buffer)) {
1559                                appendSucceeded();
1560                        }
1561                }
1562                catch (Throwable e) {
1563                        appendFailed(e, 1, false);
1564                }
1565        }
1566
1567        private boolean writeLocked(LogEvent event, LogEncoder.Buffer buffer) {
1568                if (shouldDropForReentry(lock.isHeldByCurrentThread(), flags, metrics, 1)) {
1569                        return false;
1570                }
1571                lock.lock();
1572                try {
1573                        output.write(event, buffer);
1574                        if (immediateFlush) {
1575                                output.flush();
1576                        }
1577                }
1578                finally {
1579                        lock.unlock();
1580                }
1581                return true;
1582        }
1583
1584        @Override
1585        public void append(LogEvent[] events, int count) {
1586                if (shouldDropForReentry(lock.isHeldByCurrentThread(), flags, metrics, count)) {
1587                        return;
1588                }
1589                try {
1590                        var buffer = encoder.buffer(output.bufferHints());
1591                        lock.lock();
1592                        try {
1593                                output.write(events, count, encoder, buffer);
1594                                if (immediateFlush) {
1595                                        output.flush();
1596                                }
1597                        }
1598                        finally {
1599                                lock.unlock();
1600                        }
1601                        if (count > 0) {
1602                                appendSucceeded();
1603                        }
1604                }
1605                catch (Throwable e) {
1606                        appendFailed(e, count, true);
1607                }
1608        }
1609
1610}
1611
1612/*
1613 * Like LockThreadLocalBufferLogAppender (per-thread reused buffer, encode outside any
1614 * lock) but the final write is protected by a plain `synchronized` block on this
1615 * appender's own monitor instead of a ReentrantLock. Does not extend LockLogAppender -
1616 * there is no way to acquire a monitor in one method call and release it in another, so
1617 * this appender's critical sections are written as literal synchronized blocks instead.
1618 */
1619final class SynchronizedThreadLocalBufferLogAppender extends AbstractLogAppender implements InternalLogAppender {
1620
1621        private final Object monitor = new Object();
1622
1623        // See LockThreadLocalBufferLogAppender's identical field for why this suppression is
1624        // needed.
1625        @SuppressWarnings("nullness:type.argument")
1626        private final ThreadLocal<ThreadBuffer> bufferThreadLocal;
1627
1628        SynchronizedThreadLocalBufferLogAppender(String name, LogOutput output, LogEncoder encoder,
1629                        Set<LogAppender.AppenderFlag> flags, LogAlerts alerts, LogMetrics metrics) {
1630                super(name, output, encoder, flags, alerts, metrics);
1631                this.bufferThreadLocal = ThreadLocal.withInitial(() -> new ThreadBuffer(encoder.buffer(output.bufferHints())));
1632        }
1633
1634        @Override
1635        public void clearThreadLocals() {
1636                bufferThreadLocal.remove();
1637        }
1638
1639        @Override
1640        public void append(LogEvent event) {
1641                try {
1642                        var local = bufferThreadLocal.get();
1643                        // As LockThreadLocalBufferLogAppender: the monitor alone misses reentry while
1644                        // encoding.
1645                        boolean reentrant = local.inUse || Thread.holdsLock(monitor);
1646                        if (shouldDropForReentry(reentrant, flags, metrics, 1)) {
1647                                return;
1648                        }
1649                        try {
1650                                var buffer = reentrant ? encoder.buffer(output.bufferHints()) : local.acquire();
1651                                encoder.encode(event, buffer);
1652                                writeSynchronized(event, buffer);
1653                        }
1654                        finally {
1655                                if (!reentrant) {
1656                                        local.inUse = false;
1657                                }
1658                        }
1659                        appendSucceeded();
1660                }
1661                catch (Throwable e) {
1662                        appendFailed(e, 1, false);
1663                }
1664        }
1665
1666        private void writeSynchronized(LogEvent event, LogEncoder.Buffer buffer) {
1667                synchronized (monitor) {
1668                        output.write(event, buffer);
1669                        if (immediateFlush) {
1670                                output.flush();
1671                        }
1672                }
1673        }
1674
1675        @Override
1676        public void append(LogEvent[] events, int count) {
1677                try {
1678                        var local = bufferThreadLocal.get();
1679                        boolean reentrant = local.inUse || Thread.holdsLock(monitor);
1680                        if (shouldDropForReentry(reentrant, flags, metrics, count)) {
1681                                return;
1682                        }
1683                        try {
1684                                var buffer = reentrant ? encoder.buffer(output.bufferHints()) : local.acquire();
1685                                synchronized (monitor) {
1686                                        output.write(events, count, encoder, buffer);
1687                                        if (immediateFlush) {
1688                                                output.flush();
1689                                        }
1690                                }
1691                        }
1692                        finally {
1693                                if (!reentrant) {
1694                                        local.inUse = false;
1695                                }
1696                        }
1697                        if (count > 0) {
1698                                appendSucceeded();
1699                        }
1700                }
1701                catch (Throwable e) {
1702                        appendFailed(e, count, true);
1703                }
1704        }
1705
1706        @Override
1707        public void close() {
1708                synchronized (monitor) {
1709                        super.close();
1710                }
1711        }
1712
1713        @Override
1714        public List<LogEvent> act(LogAction action) {
1715                synchronized (monitor) {
1716                        return _request(action);
1717                }
1718        }
1719
1720}