001package io.jstach.rainbowgum;
002
003import java.lang.System.Logger.Level;
004import java.util.ArrayList;
005import java.util.Collection;
006import java.util.Collections;
007import java.util.EnumSet;
008import java.util.IdentityHashMap;
009import java.util.List;
010import java.util.Locale;
011import java.util.Map;
012import java.util.Objects;
013import java.util.Set;
014import java.util.concurrent.ConcurrentLinkedQueue;
015import java.util.concurrent.CopyOnWriteArrayList;
016import java.util.concurrent.locks.ReentrantLock;
017import java.util.function.Consumer;
018import java.util.function.Function;
019
020import org.jspecify.annotations.Nullable;
021
022import io.jstach.rainbowgum.LogConfig.ChangePublisher.ChangeType;
023import io.jstach.rainbowgum.LogPublisher.PublisherFactory;
024import io.jstach.rainbowgum.LogRouter.RootRouter;
025import io.jstach.rainbowgum.LogRouter.Route;
026import io.jstach.rainbowgum.LogRouter.Router;
027import io.jstach.rainbowgum.annotation.CaseChanging;
028import io.jstach.rainbowgum.filter.DedupeFilterBuilder;
029import io.jstach.rainbowgum.filter.RemapFilterBuilder;
030import io.jstach.rainbowgum.filter.ThrottleFilterBuilder;
031
032/**
033 * Routes messages to a publisher by providing a {@link Route} from a logger name and
034 * level.
035 */
036public sealed interface LogRouter extends LogLifecycle {
037
038        /**
039         * Finds a route.
040         * @param loggerName topic.
041         * @param level level.
042         * @return route never <code>null</code>.
043         */
044        public Route route(String loggerName, java.lang.System.Logger.Level level);
045
046        /**
047         * Global router which is always available.
048         * @return global root router.
049         */
050        public static RootRouter global() {
051                return GlobalLogRouter.INSTANCE;
052        }
053
054        /**
055         * A route is similar to a SLF4J Logger or System Logger but has a much simpler
056         * contract.
057         *
058         * The proper usage of Route in most cases is to call {@link #isEnabled()} before
059         * calling {@link #log(LogEvent)}.
060         *
061         * That is {@link #log(LogEvent)} does not do any checking if the event is allowed
062         * furthermore by first checking if {@link #isEnabled()} is true one can decide
063         * whether or not to create a {@link LogEvent}.
064         */
065        public sealed interface Route extends LogEventLogger {
066
067                /**
068                 * Determines if {@link #log(LogEvent)} maybe called.
069                 * @return true if log can be called.
070                 */
071                public boolean isEnabled();
072
073                /**
074                 * Route singletons and utilities.
075                 */
076                @CaseChanging
077                public enum Routes implements Route {
078
079                        /**
080                         * A route that is a NOOP and is always disabled.
081                         */
082                        NotFound {
083                                @Override
084                                public void log(LogEvent event) {
085                                }
086
087                                @Override
088                                public boolean isEnabled() {
089                                        return false;
090                                }
091
092                        };
093
094                }
095
096        }
097
098        /**
099         * Router flags for adhoc router customization.
100         */
101        @CaseChanging
102        public enum RouteFlag {
103
104                /**
105                 * The route will not use the global level resolver and will only use the level
106                 * config directly on the router.
107                 */
108                IGNORE_GLOBAL_LEVEL_RESOLVER;
109
110                static Set<RouteFlag> parse(Collection<String> value) {
111                        if (value.isEmpty()) {
112                                return EnumSet.noneOf(RouteFlag.class);
113                        }
114                        var s = EnumSet.noneOf(RouteFlag.class);
115                        for (var v : value) {
116                                s.add(parse(v));
117                        }
118                        return s;
119                }
120
121                static RouteFlag parse(String value) {
122                        return LogProperty.enumValue(RouteFlag.class, value);
123                }
124
125        }
126
127        /**
128         * Root router is a router that has child routers.
129         */
130        sealed interface RootRouter extends LogRouter permits InternalRootRouter {
131
132                /**
133                 * The sink to dispatch events to for a logger name, with <strong>no level based
134                 * gating</strong> - unlike {@link #route(String, java.lang.System.Logger.Level)},
135                 * the returned {@link LogEventLogger} always accepts
136                 * {@link LogEventLogger#log(LogEvent)} regardless of what level is currently
137                 * enabled. Use this when level gating is already handled independently (e.g. a
138                 * logger facade caching its own resolved level and re-checking it on every call)
139                 * and a level would otherwise have to be made up just to obtain a working sink.
140                 * @param loggerName topic.
141                 * @return event logger, never <code>null</code>.
142                 */
143                public LogEventLogger eventLogger(String loggerName);
144
145                /**
146                 * Level resolver to find levels for a log name.
147                 * @return level resolver.
148                 */
149                public LevelResolver levelResolver();
150
151                /**
152                 * Register for a router changes usually involving the level resolver being
153                 * updated by config.
154                 * @param router consumer that will be called with the updated router.
155                 * @apiNote its best to use the router in the consumer accept argument and not
156                 * this router even if they are usually the same.
157                 */
158                public void onChange(Consumer<? super RootRouter> router);
159
160                /**
161                 * If a logger name configuration is changeable.
162                 * @param loggerName logger name.
163                 * @return true if config changes are allowed.
164                 */
165                public boolean isChangeable(String loggerName);
166
167        }
168
169        /**
170         * Router routes messages to a publisher.
171         */
172        sealed interface Router extends LogRouter, LogEventLogger {
173
174                /**
175                 * The router name given if no router is explicitly declared.
176                 */
177                public static final String DEFAULT_ROUTER_NAME = LogProperties.DEFAULT_NAME;
178
179                /**
180                 * Level resolver.
181                 * @return level resolver.
182                 */
183                LevelResolver levelResolver();
184
185                /**
186                 * Log publisher.
187                 * @return publisher.
188                 */
189                LogPublisher publisher();
190
191                /**
192                 * Whether or not the publisher is synchronous. A synchronous publisher generally
193                 * blocks.
194                 * @return true if the publisher is synchronous.
195                 */
196                default boolean synchronous() {
197                        return publisher().synchronous();
198                }
199
200                @Override
201                default void log(LogEvent event) {
202                        /*
203                         * Only async publishers need a frozen (immutable, defensively copied) event.
204                         * A synchronous publisher fully encodes and writes the event on the calling
205                         * thread before this call returns, so there is no other thread that could
206                         * observe or race with further mutation (e.g. MDC.put/remove) of the live
207                         * event data - freezing there would just be wasted allocation on the hot
208                         * path. Freeze is a noop if the event is already frozen.
209                         */
210                        if (!synchronous()) {
211                                event = event.freeze();
212                        }
213                        publisher().log(event);
214                }
215
216                /**
217                 * Creates a builder from config.
218                 * @param name name of the route which the publisher will inherit.
219                 * @param config config.
220                 * @return builder.
221                 */
222                static Builder builder(String name, LogConfig config) {
223                        /*
224                         * Eagerly triggers LogProperties' own key-parameter-value validation now:
225                         * needed because a fully-explicit route (explicit appenders, level,
226                         * publisher) never triggers a single keyed property lookup on its own, so
227                         * without this a malformed name would otherwise never be validated. Wrapped
228                         * into a ValidationException the same way a generated builder's constructor
229                         * is, so a bad name reports the same exception type regardless of whether it
230                         * came from logging.routes (RainbowGum.Builder's own validateNames call) or a
231                         * direct programmatic builder(name, config) call like this one.
232                         */
233                        try {
234                                LogProperties.interpolateNamedKey(LogProperties.ROUTE_LEVEL_PREFIX, name);
235                        }
236                        catch (IllegalArgumentException e) {
237                                throw LogProperty.ValidationException.of(LogRouter.class, e);
238                        }
239                        return new Builder(name, config);
240                }
241
242                /**
243                 * Drops or changes a route's events before its router gets them, for example to
244                 * remove noisy events, change their level or mask their message with
245                 * {@link LogEvent#rewrite(LogEvent, LogEvent.Rewriter)}. Filters are selected by
246                 * name with the {@value LogProperties#ROUTE_FILTERS_PROPERTY} property: <pre>
247                 * logging.route.default.filters=quietHealthChecks,maskCards
248                 * </pre>
249                 * <p>
250                 * They run in the order listed, each on the event the previous one returned,
251                 * after filters added with {@link Builder#filter(Filter)}. A filter is only given
252                 * events whose level the route enables, so it cannot make a disabled event
253                 * appear. When a filter returns an event at a level the route does not enable for
254                 * the event's logger, the route drops it and later filters do not see it.
255                 * <p>
256                 * A filter changes only what its route sees. Other routes get the original event.
257                 * <p>
258                 * Filters must be thread-safe. One instance filters every event of its route,
259                 * possibly from several threads at once. Events may already be
260                 * {@linkplain LogEvent#freeze() frozen}, for example when another route uses an
261                 * async publisher. {@link LogEvent#message()} is the unformatted message in
262                 * either case.
263                 * <p>
264                 * Filters are registered by name with
265                 * {@link #register(ServiceRegistry, String, Provider)}. A name that is not
266                 * registered fails when the route is built, with an error listing the registered
267                 * names. A filter's own properties start with
268                 * {@value LogProperties#FILTER_PREFIX}, where <code>filter</code> is the name it
269                 * is selected with. These standard filters are registered when the
270                 * {@link LogConfig} is created:
271                 * <ul>
272                 * <li><code>throttle</code>: limits how many events are kept per second, see
273                 * {@link io.jstach.rainbowgum.filter.ThrottleFilterBuilder}.</li>
274                 * <li><code>dedupe</code>: drops repeats of the same message, see
275                 * {@link io.jstach.rainbowgum.filter.DedupeFilterBuilder}.</li>
276                 * <li><code>remap</code>: moves events from one level to another, see
277                 * {@link io.jstach.rainbowgum.filter.RemapFilterBuilder}.</li>
278                 * </ul>
279                 */
280                @FunctionalInterface
281                public interface Filter {
282
283                        /**
284                         * Filters an event.
285                         * @param event event the route enables, or the event the previous filter
286                         * returned.
287                         * @return the event to pass on, which may be the given event or a different
288                         * one such as {@link LogEvent#withLevel(LogEvent, Level)} returns, or
289                         * <code>null</code> to drop it.
290                         */
291                        @Nullable LogEvent filterOrNull(LogEvent event);
292
293                        /**
294                         * Registers a filter under a name so routes can select it with
295                         * {@value LogProperties#ROUTE_FILTERS_PROPERTY}, usually from a
296                         * {@link io.jstach.rainbowgum.spi.RainbowGumServiceProvider.Configurator}. A
297                         * name that is already registered is not replaced.
298                         * @param registry usually {@link LogConfig#serviceRegistry()}.
299                         * @param name the name used in the property.
300                         * @param provider creates the filter, given the route's name and config.
301                         */
302                        public static void register(ServiceRegistry registry, String name, Provider provider) {
303                                registry.put(Provider.class, name, provider);
304                        }
305
306                        /**
307                         * Creates a filter for a route, given the route's name and config. It is
308                         * called once each time a route that lists its name is built, not for each
309                         * event.
310                         */
311                        @FunctionalInterface
312                        public interface Provider extends LogProvider<Filter> {
313
314                        }
315
316                }
317
318                /**
319                 * Router builder.
320                 */
321                public final class Builder extends LevelResolver.AbstractBuilder<Builder> implements LogConfig.ConfigSupport {
322
323                        private final LogConfig config;
324
325                        private final String name;
326
327                        private final EnumSet<RouteFlag> flags = EnumSet.noneOf(RouteFlag.class);
328
329                        private List<LogProvider<LogAppender>> appenders = new ArrayList<>();
330
331                        private final List<Filter> filters = new ArrayList<>();
332
333                        private Builder(String name, LogConfig config) {
334                                this.name = Objects.requireNonNull(name);
335                                this.config = config;
336                        }
337
338                        private @Nullable PublisherFactory publisher;
339
340                        @Override
341                        protected Builder self() {
342                                return this;
343                        }
344
345                        /**
346                         * Gets the currently bound config.
347                         * @return config.
348                         */
349                        @Override
350                        public LogConfig config() {
351                                return this.config;
352                        }
353
354                        /**
355                         * Adds a flag.
356                         * @param flag flag added if not already added.
357                         * @return this.
358                         */
359                        public Builder flag(RouteFlag flag) {
360                                flags.add(flag);
361                                return this;
362                        }
363
364                        /**
365                         * Adds an appender by giving an appender builder to a consumer.
366                         * @param name appender name.
367                         * @param consumer consumer.
368                         * @return this builder.
369                         */
370                        public Builder appender(String name, Consumer<LogAppender.Builder> consumer) {
371                                var builder = LogAppender.builder(name);
372                                consumer.accept(builder);
373                                this.appenders.add(builder.build());
374                                return this;
375                        }
376
377                        /**
378                         * Adds an appender.
379                         * @param appender appender provider.
380                         * @return this builder.
381                         */
382                        public Builder appender(LogProvider<LogAppender> appender) {
383                                this.appenders.add(Objects.requireNonNull(appender));
384                                return self();
385                        }
386
387                        /**
388                         * Sets the publisher. Only one publisher to router.
389                         * @param publisher publisher.
390                         * @return this builder.
391                         */
392                        public Builder publisher(PublisherFactory publisher) {
393                                this.publisher = publisher;
394                                return self();
395                        }
396
397                        /**
398                         * Adds a filter that runs before the filters listed in
399                         * {@value LogProperties#ROUTE_FILTERS_PROPERTY}.
400                         * @param filter filter.
401                         * @return this.
402                         * @see Filter
403                         */
404                        public Builder filter(Filter filter) {
405                                this.filters.add(Objects.requireNonNull(filter));
406                                return this;
407                        }
408
409                        /**
410                         * Builds the router.
411                         * @return router.
412                         */
413                        Router build() {
414                                String name = this.name;
415                                flags.addAll(rawValue(config.properties()
416                                        .forKey(LogProperties.ROUTE_FLAGS_PROPERTY, name)
417                                        .ofList()
418                                        .map(RouteFlag::parse)
419                                        .or(EnumSet.noneOf(RouteFlag.class))).value());
420                                List<Filter> filters = new ArrayList<>(this.filters);
421                                for (String filterName : rawValue(
422                                                config.properties().forKey(LogProperties.ROUTE_FILTERS_PROPERTY, name).ofList().or(List.of()))
423                                        .value()) {
424                                        filters.add(filter(filterName.strip(), name, config));
425                                }
426                                String routerLevelPrefix = LogProperties.interpolateNamedKey(LogProperties.ROUTE_LEVEL_PREFIX, name);
427
428                                /*
429                                 * The route's own level config is resolved in isolation from the global
430                                 * level resolver so that a route level override takes priority per logger
431                                 * name instead of merging with global by prefix specificity (a more
432                                 * specific global override would otherwise win over a coarser route
433                                 * override even though the route is meant to take precedence). If the
434                                 * route has no opinion at all for a given name (resolves to Level.ALL)
435                                 * resolution falls through to the global resolver for that name, unless
436                                 * IGNORE_GLOBAL_LEVEL_RESOLVER is set in which case global is never
437                                 * consulted.
438                                 */
439                                var routeLevelResolverBuilder = LevelResolver.builder();
440                                var currentConfig = buildLevelConfigOrNull();
441                                if (currentConfig != null) {
442                                        routeLevelResolverBuilder.config(currentConfig);
443                                }
444                                routeLevelResolverBuilder.config(config.properties(), routerLevelPrefix);
445                                /*
446                                 * config.levelResolver() (the global resolver) has no caching of its own
447                                 * - the previous single merged CompositeLevelConfig relied on being
448                                 * wrapped in one outer cache for the whole route+global composition.
449                                 * LevelResolver.Builder.build() restores that guarantee (level resolvers
450                                 * are cached / static, see LevelResolver's class documentation) for the
451                                 * combined route+global resolver below.
452                                 */
453                                if (!flags.contains(RouteFlag.IGNORE_GLOBAL_LEVEL_RESOLVER)) {
454                                        routeLevelResolverBuilder.fallback(config.levelResolver());
455                                }
456                                var levelResolver = routeLevelResolverBuilder.build().provide(name, config);
457
458                                /*
459                                 * The root level might not be set by the route or globally, even when the
460                                 * route sets levels for some loggers.
461                                 */
462                                var level = levelResolver.resolveLevel("");
463                                Objects.requireNonNull(level);
464                                if (level == System.Logger.Level.ALL) {
465                                        /*
466                                         * Neither the route nor the global level resolver have a root level.
467                                         * Without this fallback loggers they have no opinion on would be ALL,
468                                         * which the builders and other places turn into TRACE.
469                                         */
470                                        levelResolver = LevelResolver.builder()
471                                                .resolver(levelResolver)
472                                                .fallback(StaticLevelResolver.INFO)
473                                                .build()
474                                                .provide(name, config);
475                                }
476
477                                var _levelResolver = levelResolver;
478                                /*
479                                 * This routers level resolver needs to be notified if config changes.
480                                 */
481                                config.changePublisher().subscribe(c -> {
482                                        _levelResolver.clear();
483                                });
484                                var publisher = this.publisher;
485
486                                List<LogProvider<LogAppender>> appenders = new ArrayList<>(this.appenders);
487                                if (appenders.isEmpty()) {
488                                        DefaultAppenderRegistry.appenders(config, name) //
489                                                .stream() //
490                                                .forEach(appenders::add);
491                                }
492
493                                if (publisher == null) {
494                                        var properties = config.properties();
495                                        publisher = rawValue(properties.forKey(LogProperties.ROUTE_PUBLISHER_PROPERTY, name)
496                                                .ofProviderRef()
497                                                .map(r -> config.publisherRegistry().provide(r))
498                                                .or(() -> LogPublisher.SyncLogPublisher.builder().build())).value();
499                                }
500
501                                var apps = new LogAppender.Appenders(name, config, appenders);
502                                var pub = publisher.create(name, config, apps);
503                                if (pub.synchronous()) {
504                                        warnNetworkOutputs(name, apps, config);
505                                }
506                                /*
507                                 * Register the publisher and its appenders for lookup like status checks
508                                 * (see LogReporter). Registering "apps" itself rather than its resolved
509                                 * list lets a lookup happen after the fact regardless of whether the
510                                 * publisher called asList()/asSingle() eagerly here or lazily later, and
511                                 * Appenders.resolvedOrNull() returns null if the publisher never calls
512                                 * either (meaning it does not use the appenders this ordinary way at
513                                 * all).
514                                 */
515                                config.serviceRegistry().put(LogPublisher.class, name, pub);
516                                config.serviceRegistry().put(LogAppender.Appenders.class, name, apps);
517                                var router = new SimpleRouter(name, pub, levelResolver);
518                                if (filters.isEmpty()) {
519                                        return router;
520                                }
521                                return new FilteringRouter(name, router, filters.toArray(Filter[]::new),
522                                                config.metrics().gauge(LogMetrics.EVENTS_FILTERED_METRIC, Level.INFO));
523                        }
524
525                        /*
526                         * A network output written on the logging thread can block the application
527                         * when the endpoint is slow or stalled. The URI is not shown: it can hold
528                         * credentials.
529                         */
530                        private static void warnNetworkOutputs(String routeName, LogAppender.Appenders apps, LogConfig config) {
531                                var resolved = apps.resolvedOrNull();
532                                if (resolved == null) {
533                                        return;
534                                }
535                                for (var appender : resolved) {
536                                        List<? extends DirectLogAppender> directs = switch (appender) {
537                                                case DirectLogAppender d -> List.of(d);
538                                                case CompositeLogAppender c -> List.of(c.appenders());
539                                                default -> List.of();
540                                        };
541                                        for (var direct : directs) {
542                                                if (direct.output().type() == LogOutput.OutputType.NETWORK) {
543                                                        config.alerts()
544                                                                .warn(LogRouter.class, "Route '" + routeName + "' sends appender '" + direct.name()
545                                                                                + "' to a network output with a synchronous publisher. Network I/O can block the logging thread. "
546                                                                                + "Consider an asynchronous publisher, for example "
547                                                                                + LogProperties.interpolateKey(LogProperties.ROUTE_PUBLISHER_PROPERTY,
548                                                                                                Map.of(LogProperties.NAME, routeName))
549                                                                                + "=async:///.");
550                                                }
551                                        }
552                                }
553                        }
554
555                        private static Filter filter(String filterName, String routeName, LogConfig config) {
556                                var provider = config.serviceRegistry().findOrNull(Filter.Provider.class, filterName);
557                                if (provider != null) {
558                                        return provider.provide(routeName, config);
559                                }
560                                var available = new java.util.TreeSet<String>();
561                                config.serviceRegistry().forEach(Filter.Provider.class, (n, p) -> available.add(n));
562                                throw new IllegalArgumentException("Unknown filter '" + filterName + "' for route '" + routeName
563                                                + "'. Available filters: " + String.join(", ", available));
564                        }
565
566                        /*
567                         * Both flags and publisher above already have a fallback applied (Missing is
568                         * impossible), but a present-but-malformed value must still surface its raw,
569                         * unwrapped exception - not a "Validation failed for Builder:" wrapping,
570                         * which would also change the exception's public type away from
571                         * PropertyConvertException (see ConfigFailureTest's bogus-scheme publisher
572                         * case). LogProperty.Result no longer exposes value() itself (a bare Result
573                         * might still be Missing), so this just narrows to
574                         * LogProperty.ValidatedResult - true for every concrete Result - without
575                         * going through a Validator at all.
576                         */
577                        private static <T> LogProperty.ValidatedResult<T> rawValue(LogProperty.Result<T> result) {
578                                return switch (result) {
579                                        case LogProperty.ValidatedResult<T> vr -> vr;
580                                };
581                        }
582
583                }
584
585        }
586
587}
588
589record SimpleRouter(String name, LogPublisher publisher, LevelResolver levelResolver) implements Router, Route {
590
591        @Override
592        public void close() {
593                publisher.close();
594        }
595
596        @Override
597        public Route route(String loggerName, java.lang.System.Logger.Level level) {
598                if (levelResolver().isEnabled(loggerName, level)) {
599                        return this;
600                }
601                return Route.Routes.NotFound;
602        }
603
604        @Override
605        public boolean isEnabled() {
606                return true;
607        }
608
609        @Override
610        public void start(LogConfig config) {
611                publisher.start(config);
612        }
613
614}
615
616/*
617 * Registers the standard filters under their names. Called when the LogConfig is created,
618 * before any configurator can register a name.
619 */
620final class StandardFilters {
621
622        private StandardFilters() {
623        }
624
625        static void register(ServiceRegistry registry) {
626                Router.Filter.register(registry, "throttle",
627                                (route, config) -> new ThrottleFilterBuilder(route, "throttle").metrics(config.metrics())
628                                        .fromProperties(config.properties())
629                                        .build());
630                Router.Filter.register(registry, "dedupe",
631                                (route, config) -> new DedupeFilterBuilder(route, "dedupe").metrics(config.metrics())
632                                        .fromProperties(config.properties())
633                                        .build());
634                Router.Filter.register(registry, "remap",
635                                (route, config) -> new RemapFilterBuilder(route, "remap").fromProperties(config.properties()).build());
636        }
637
638}
639
640/*
641 * Runs a route's filters in front of its router.
642 */
643@SuppressWarnings("ArrayRecordComponent")
644record FilteringRouter(String name, SimpleRouter router, Router.Filter[] filters,
645                LogMetrics.Gauge filtered) implements Router, Route {
646
647        @Override
648        public void log(LogEvent event) {
649                LogEvent e = event;
650                for (var filter : filters) {
651                        var level = e.level();
652                        var loggerName = e.loggerName();
653                        e = filter.filterOrNull(e);
654                        if (e == null || ((e.level() != level || !e.loggerName().equals(loggerName))
655                                        && !router.levelResolver().isEnabled(e.loggerName(), e.level()))) {
656                                filtered.increment();
657                                return;
658                        }
659                }
660                router.log(e);
661        }
662
663        @Override
664        public Route route(String loggerName, Level level) {
665                if (router.route(loggerName, level).isEnabled()) {
666                        return this;
667                }
668                return Route.Routes.NotFound;
669        }
670
671        @Override
672        public boolean isEnabled() {
673                return true;
674        }
675
676        @Override
677        public LevelResolver levelResolver() {
678                return router.levelResolver();
679        }
680
681        @Override
682        public LogPublisher publisher() {
683                return router.publisher();
684        }
685
686        @Override
687        public boolean synchronous() {
688                return router.synchronous();
689        }
690
691        @Override
692        public void start(LogConfig config) {
693                router.start(config);
694        }
695
696        @Override
697        public void close() {
698                router.close();
699        }
700
701}
702
703sealed interface InternalRootRouter extends RootRouter {
704
705        /**
706         * Sets the root router.
707         * @param router root router.
708         * @return events the replaced queue dropped because it was full, or zero.
709         */
710        static long setRouter(RootRouter router) {
711                if (GlobalLogRouter.INSTANCE == router) {
712                        return 0;
713                }
714                var original = GlobalLogRouter.INSTANCE.bind((InternalRootRouter) router);
715                return original instanceof QueueEventsRouter q ? q.dropped() : 0;
716        }
717
718        static InternalRootRouter of(List<? extends Router> routes, LogConfig config) {
719
720                if (routes.isEmpty()) {
721                        throw new IllegalArgumentException("atleast one route is required");
722                }
723                List<Router> sorted = new ArrayList<>();
724                /*
725                 * We add the async routers first
726                 */
727                Set<Router> matched = Collections.newSetFromMap(new IdentityHashMap<Router, Boolean>());
728                for (var r : routes) {
729                        if (!r.synchronous()) {
730                                if (matched.add(r)) {
731                                        sorted.add(r);
732                                }
733                        }
734                }
735                for (var r : routes) {
736                        if (r.synchronous()) {
737                                if (matched.add(r)) {
738                                        sorted.add(r);
739                                }
740                        }
741                }
742                routes = sorted;
743                LevelResolver.Builder resolverBuilder = LevelResolver.builder();
744                routes.stream().map(Router::levelResolver).forEach(resolverBuilder::resolver);
745                var globalLevelResolver = resolverBuilder.build().provide("", config);
746
747                Router[] array = routes.toArray(new Router[] {});
748
749                RouteChangePublisher changePublisher = new RouteChangePublisher(
750                                s -> config.changePublisher().allowedChanges(s).contains(ChangeType.LEVEL));
751                if (array.length == 1) {
752                        var r = array[0];
753                        return new SingleRootRouter(r, changePublisher);
754                }
755                return new CompositeLogRouter(array, globalLevelResolver, changePublisher);
756        }
757
758        default boolean isEnabled(String loggerName, java.lang.System.Logger.Level level) {
759                return route(loggerName, level).isEnabled();
760
761        }
762
763        default void drain(InternalRootRouter delegate) {
764
765        }
766
767        @Override
768        default void onChange(Consumer<? super RootRouter> router) {
769                changePublisher().add(router);
770        }
771
772        public RouteChangePublisher changePublisher();
773
774        @Override
775        default boolean isChangeable(String loggerName) {
776                return changePublisher().loggerChangeable.apply(loggerName);
777        }
778
779        final class RouteChangePublisher {
780
781                private final Collection<Consumer<? super RootRouter>> consumers = new CopyOnWriteArrayList<Consumer<? super RootRouter>>();
782
783                private final Function<String, Boolean> loggerChangeable;
784
785                RouteChangePublisher(Function<String, Boolean> loggerChangeable) {
786                        super();
787                        this.loggerChangeable = loggerChangeable;
788                }
789
790                void add(Consumer<? super RootRouter> consumer) {
791                        consumers.add(consumer);
792                }
793
794                void publish(RootRouter router) {
795                        for (var c : consumers) {
796                                c.accept(router);
797                        }
798                }
799
800                void transferTo(RouteChangePublisher changePublisher) {
801                        changePublisher.consumers.addAll(consumers);
802                        this.consumers.clear();
803                }
804
805        }
806
807}
808
809record SingleRootRouter(Router router, RouteChangePublisher changePublisher) implements InternalRootRouter {
810
811        @Override
812        public void start(LogConfig config) {
813                router.start(config);
814        }
815
816        @Override
817        public void close() {
818                router.close();
819        }
820
821        @Override
822        public LevelResolver levelResolver() {
823                return router.levelResolver();
824        }
825
826        @Override
827        public Route route(String loggerName, Level level) {
828                return router.route(loggerName, level);
829        }
830
831        @Override
832        public LogEventLogger eventLogger(String loggerName) {
833                return router;
834        }
835
836}
837
838@SuppressWarnings("ArrayRecordComponent") // TODO revisit perf
839record CompositeLogRouter(Router[] routers, LevelResolver levelResolver,
840                RouteChangePublisher changePublisher) implements InternalRootRouter, Route {
841
842        @Override
843        public Route route(String loggerName, Level level) {
844                /*
845                 * The assumption is the provided level resolver is a cached composite level
846                 * resolver of all the routers.
847                 */
848                if (levelResolver.isEnabled(loggerName, level)) {
849                        return this;
850                }
851                return Routes.NotFound;
852        }
853
854        @Override
855        public LogEventLogger eventLogger(String loggerName) {
856                /*
857                 * log(LogEvent) below already fans out to every child router regardless of how it
858                 * was reached, so this composite is already its own sink - no per-child selection
859                 * happens until log() actually runs.
860                 */
861                return this;
862        }
863
864        @Override
865        public void log(LogEvent event) {
866                for (var router : routers) {
867                        var route = router.route(event.loggerName(), event.level());
868                        if (route.isEnabled()) {
869                                /*
870                                 * We assume async routers are earlier in the array.
871                                 */
872                                if (!router.synchronous()) {
873                                        /*
874                                         * Now all events are frozen from here onward to guarantee that the
875                                         * synchronous routers see the same thing as the async routers.
876                                         *
877                                         * Freeze is a noop if it already frozen.
878                                         */
879                                        event = event.freeze();
880                                }
881                                route.log(event);
882                        }
883                }
884        }
885
886        @Override
887        public boolean isEnabled() {
888                return true;
889        }
890
891        @Override
892        public void start(LogConfig config) {
893                for (var r : routers) {
894                        r.start(config);
895                }
896        }
897
898        @Override
899        public void close() {
900                for (var r : routers) {
901                        r.close();
902                }
903        }
904}
905
906/*
907 * Holds events while no Rainbow Gum is bound, before one is bound or after one is closed.
908 * Events are frozen when queued, so their arguments are formatted on the caller's thread
909 * and not kept alive, and the queue holds at most maxSize of them. Once drained, events
910 * still arriving, from a log call racing the drain or a logger holding this queue, are
911 * passed on to the global router instead of being stranded here.
912 */
913final class QueueEventsRouter implements InternalRootRouter, Route {
914
915        static final int DEFAULT_MAX_SIZE = 1000;
916
917        private final ConcurrentLinkedQueue<LogEvent> events = new ConcurrentLinkedQueue<>();
918
919        private int size;
920
921        private long dropped;
922
923        private final int maxSize;
924
925        private @Nullable InternalRootRouter successor;
926
927        private final LevelResolver levelResolver;
928
929        private final LevelResolver errorLevelResolver;
930
931        private final RouteChangePublisher changePublisher = new RouteChangePublisher(s -> true);
932
933        static QueueEventsRouter of() {
934                var validator = LogProperty.Validator.of(QueueEventsRouter.class);
935                var queueLevel = queueLevel().validate(validator);
936                var errorLevel = errorLevel().validate(validator);
937                var maxSize = maxSize().validate(validator);
938                validator.validate();
939                return new QueueEventsRouter(StaticLevelResolver.of(queueLevel.value()),
940                                StaticLevelResolver.of(errorLevel.value()), maxSize.value());
941        }
942
943        private static LogProperty.Result<Integer> maxSize() {
944                var properties = LogProperties.StandardProperties.SYSTEM_PROPERTIES;
945                return properties.forKey(LogProperties.GLOBAL_QUEUE_SIZE_PROPERTY).ofInt().map(size -> {
946                        if (size < 0) {
947                                throw new IllegalArgumentException("must not be negative");
948                        }
949                        return size;
950                }).or(DEFAULT_MAX_SIZE);
951        }
952
953        private static LogProperty.Result<Level> queueLevel() {
954                var properties = LogProperties.StandardProperties.SYSTEM_PROPERTIES;
955                return properties.forKey(LogProperties.GLOBAL_QUEUE_LEVEL_PROPERTY)
956                        .ofString()
957                        .map(LevelResolver::parseLevel)
958                        .or(Level.INFO);
959        }
960
961        private static final LogProperty.Result<Level> errorLevel() {
962                var properties = LogProperties.StandardProperties.SYSTEM_PROPERTIES;
963                return properties.forKey(LogProperties.GLOBAL_QUEUE_ERROR_PROPERTY)
964                        .ofString()
965                        .map(LevelResolver::parseLevel)
966                        .or(Level.ERROR);
967        }
968
969        private QueueEventsRouter(LevelResolver levelResolver, LevelResolver errorLevelResolver, int maxSize) {
970                super();
971                this.levelResolver = levelResolver;
972                this.errorLevelResolver = errorLevelResolver;
973                this.maxSize = maxSize;
974        }
975
976        long dropped() {
977                synchronized (events) {
978                        return dropped;
979                }
980        }
981
982        @Override
983        public LevelResolver levelResolver() {
984                return levelResolver;
985        }
986
987        @Override
988        public Route route(String loggerName, Level level) {
989                if (levelResolver.isEnabled(loggerName, level)) {
990                        return this;
991                }
992                return Routes.NotFound;
993        }
994
995        @Override
996        public LogEventLogger eventLogger(String loggerName) {
997                return this;
998        }
999
1000        @Override
1001        public void start(LogConfig config) {
1002        }
1003
1004        @Override
1005        public void close() {
1006                synchronized (events) {
1007                        while (events.poll() != null) {
1008                                size--;
1009                        }
1010                }
1011        }
1012
1013        @Override
1014        public void log(LogEvent event) {
1015                InternalRootRouter next;
1016                boolean full;
1017                synchronized (events) {
1018                        next = successor;
1019                        full = next == null && size >= maxSize;
1020                        if (full) {
1021                                dropped++;
1022                        }
1023                        else if (next == null) {
1024                                size++;
1025                        }
1026                }
1027                if (next != null) {
1028                        forwardEvent(next, event);
1029                        return;
1030                }
1031                if (!full) {
1032                        LogEvent frozen;
1033                        try {
1034                                // Formatting can reenter logging or bind a gum. Keep it outside
1035                                // the queue monitor, while reserving capacity for this event.
1036                                frozen = event.freeze();
1037                        }
1038                        catch (RuntimeException | Error e) {
1039                                synchronized (events) {
1040                                        size--;
1041                                }
1042                                throw e;
1043                        }
1044                        synchronized (events) {
1045                                next = successor;
1046                                if (next == null) {
1047                                        events.add(frozen);
1048                                }
1049                                else {
1050                                        size--;
1051                                }
1052                        }
1053                        if (next != null) {
1054                                forwardEvent(next, frozen);
1055                        }
1056                }
1057                if (errorLevelResolver.isEnabled(event.loggerName(), event.level())) {
1058                        MetaLog.error(event);
1059                }
1060        }
1061
1062        @Override
1063        public void drain(InternalRootRouter delegate) {
1064                synchronized (events) {
1065                        successor = delegate;
1066                }
1067                while (true) {
1068                        LogEvent event;
1069                        synchronized (events) {
1070                                event = events.poll();
1071                                if (event == null) {
1072                                        return;
1073                                }
1074                                size--;
1075                        }
1076                        forwardEvent(delegate, event);
1077                }
1078        }
1079
1080        private static void forwardEvent(InternalRootRouter delegate, LogEvent event) {
1081                var route = delegate.route(event.loggerName(), event.level());
1082                if (route.isEnabled()) {
1083                        route.log(event);
1084                }
1085        }
1086
1087        @Override
1088        public boolean isEnabled() {
1089                return true;
1090        }
1091
1092        @Override
1093        public RouteChangePublisher changePublisher() {
1094                return this.changePublisher;
1095        }
1096
1097}
1098
1099@SuppressWarnings("ImmutableEnumChecker")
1100enum GlobalLogRouter implements InternalRootRouter, Route {
1101
1102        INSTANCE;
1103
1104        private volatile InternalRootRouter delegate = QueueEventsRouter.of();
1105
1106        private final ReentrantLock drainLock = new ReentrantLock();
1107
1108        InternalRootRouter currentRouter() {
1109                return delegate;
1110        }
1111
1112        /*
1113         * A bind can fail in a route subscriber before the delegate switches, or while
1114         * draining queued events after it switches. Restore both routing and subscribers
1115         * before the failed candidate is closed. A drained queue cannot be reused because it
1116         * may forward back to the global router.
1117         */
1118        @SuppressWarnings("ReferenceEquality")
1119        void restoreAfterFailedBind(InternalRootRouter previous, InternalRootRouter failed) {
1120                drainLock.lock();
1121                try {
1122                        if (failed == this || (delegate != previous && delegate != failed)) {
1123                                return;
1124                        }
1125                        InternalRootRouter restored = previous instanceof QueueEventsRouter ? QueueEventsRouter.of() : previous;
1126                        failed.changePublisher().transferTo(restored.changePublisher());
1127                        if (delegate != restored && delegate != failed) {
1128                                delegate.changePublisher().transferTo(restored.changePublisher());
1129                        }
1130                        this.delegate = restored;
1131                        restored.changePublisher().publish(restored);
1132                }
1133                finally {
1134                        drainLock.unlock();
1135                }
1136        }
1137
1138        @Override
1139        public LevelResolver levelResolver() {
1140                return delegate.levelResolver();
1141        }
1142
1143        @Override
1144        public boolean isEnabled() {
1145                return true;
1146        }
1147
1148        @Override
1149        public void log(LogEvent event) {
1150                InternalRootRouter d = delegate;
1151                if (d instanceof QueueEventsRouter q) {
1152                        q.log(event);
1153                }
1154                else {
1155                        var route = d.route(event.loggerName(), event.level());
1156                        if (route.isEnabled()) {
1157                                route.log(event);
1158                        }
1159                }
1160        }
1161
1162        @Override
1163        public Route route(String loggerName, Level level) {
1164                return this.delegate.route(loggerName, level);
1165        }
1166
1167        @Override
1168        public LogEventLogger eventLogger(String loggerName) {
1169                return this.delegate.eventLogger(loggerName);
1170        }
1171
1172        @Override
1173        public boolean isEnabled(String loggerName, Level level) {
1174                return this.delegate.isEnabled(loggerName, level);
1175        }
1176
1177        @Override
1178        public RouteChangePublisher changePublisher() {
1179                return this.delegate.changePublisher();
1180        }
1181
1182        @Override
1183        public void drain(InternalRootRouter delegate) {
1184                _drain(delegate);
1185        }
1186
1187        /*
1188         * Binds the delegate and returns the router it replaced.
1189         */
1190        InternalRootRouter bind(InternalRootRouter delegate) {
1191                return _drain(delegate);
1192        }
1193
1194        private InternalRootRouter _drain(InternalRootRouter delegate) {
1195                if (delegate == this) {
1196                        throw new IllegalStateException("bug");
1197                }
1198                drainLock.lock();
1199                try {
1200                        var original = this.delegate;
1201                        // Transferring a publisher to itself would clear its subscribers.
1202                        @SuppressWarnings("ReferenceEquality")
1203                        boolean same = original == delegate;
1204                        if (same) {
1205                                return original;
1206                        }
1207                        // Existing changeable loggers must follow every binding, including removal.
1208                        original.changePublisher().transferTo(delegate.changePublisher());
1209                        delegate.changePublisher().publish(delegate);
1210                        this.delegate = Objects.requireNonNull(delegate);
1211                        if (original instanceof QueueEventsRouter queue) {
1212                                queue.drain(this);
1213                        }
1214                        else {
1215                                original.drain(delegate);
1216                        }
1217                        return original;
1218                }
1219                finally {
1220                        drainLock.unlock();
1221                }
1222        }
1223
1224        @Override
1225        public void start(LogConfig config) {
1226        }
1227
1228        @Override
1229        public void close() {
1230                var d = _drain(QueueEventsRouter.of());
1231                d.close();
1232        }
1233
1234}