Add customizable graceful shutdown options for Client's EventLoopGroups (#5813) (#6588)

**Motivation:**

Netty's default 2-second graceful shutdown delay can be excessive for
applications requiring frequent restarts. Customization allows users to
reduce teardown time.

**Modifications:**

- Added APIs in `ClientFactoryBuilder` to set custom shutdown quiet
period and timeout.
- Introduced related configuration options in `ClientFactoryOptions`.
- Adapted shutdown behavior to respect custom defaults or explicit user
configurations.
- Introduced `EventLoopGroupBuilder` for creating Netty
`EventLoopGroup`s with custom graceful shutdown parameters (quiet period
and timeout).
- Added `EventLoopGroups.builder()` to provide a fluent API for
`EventLoopGroup` configuration.
- Added `ShutdownConfigurableEventLoopGroup` and
`DelegatingEventLoopGroup` to apply pre-configured shutdown delays when
`shutdownGracefully()` is called.
- Added `ServerBuilder.bossGroupFactory()` to allow customization of
boss `EventLoopGroup`s and their shutdown behavior.

**Result:**

- Clients can now configure graceful shutdown delays, enhancing
flexibility for applications with frequent lifecycle changes.
- Users can now minimize `Server` and `ClientFactory` shutdown time by
customizing the graceful shutdown quiet period and timeout for
`EventLoopGroup`s.
- Improved flexibility and responsiveness for applications with frequent
start/stop cycles.

This pull request combines two previously discussed and verified pull
requests:

- #6528
- #6586

Multiple separated commits from previous PRs were squashed to two clean
commits and conflicts with `main` branch has been resolved. Changes were
pre-approved by @ikhoon and @jrhee17

Author: novoj

core/src/main/java/com/linecorp/armeria/common/util/DelegatingEventLoopGroup.java

@@ -0,0 +1,200 @@
+/*
+ * Copyright 2026 LINE Corporation
+ *
+ * LINE Corporation licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+package com.linecorp.armeria.common.util;
+
+import static java.util.Objects.requireNonNull;
+
+import java.util.Collection;
+import java.util.Iterator;
+import java.util.List;
+import java.util.concurrent.Callable;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+import io.netty.channel.Channel;
+import io.netty.channel.ChannelFuture;
+import io.netty.channel.ChannelPromise;
+import io.netty.channel.EventLoop;
+import io.netty.channel.EventLoopGroup;
+import io.netty.util.concurrent.EventExecutor;
+import io.netty.util.concurrent.Future;
+import io.netty.util.concurrent.ScheduledFuture;
+
+/**
+ * A delegating {@link EventLoopGroup} that forwards all calls to the underlying delegate.
+ */
+class DelegatingEventLoopGroup implements EventLoopGroup {
+
+    private final EventLoopGroup delegate;
+
+    /**
+     * Creates a new instance.
+     *
+     * @param delegate the {@link EventLoopGroup} to delegate to
+     */
+    DelegatingEventLoopGroup(EventLoopGroup delegate) {
+        this.delegate = requireNonNull(delegate, "delegate");
+    }
+
+    /**
+     * Returns the underlying {@link EventLoopGroup}.
+     */
+    protected EventLoopGroup delegate() {
+        return delegate;
+    }
+
+    @Override
+    public EventLoop next() {
+        return delegate.next();
+    }
+
+    @Override
+    public Iterator<EventExecutor> iterator() {
+        return delegate.iterator();
+    }
+
+    @Override
+    public ChannelFuture register(Channel channel) {
+        return delegate.register(channel);
+    }
+
+    @Override
+    public ChannelFuture register(ChannelPromise promise) {
+        return delegate.register(promise);
+    }
+
+    @Deprecated
+    @Override
+    public ChannelFuture register(Channel channel, ChannelPromise promise) {
+        return delegate.register(channel, promise);
+    }
+
+    @Override
+    public boolean isShuttingDown() {
+        return delegate.isShuttingDown();
+    }
+
+    @Override
+    public Future<?> shutdownGracefully() {
+        return delegate.shutdownGracefully();
+    }
+
+    @Override
+    public Future<?> shutdownGracefully(long quietPeriod, long timeout, TimeUnit unit) {
+        return delegate.shutdownGracefully(quietPeriod, timeout, unit);
+    }
+
+    @Override
+    public Future<?> terminationFuture() {
+        return delegate.terminationFuture();
+    }
+
+    @Deprecated
+    @Override
+    public void shutdown() {
+        delegate.shutdown();
+    }
+
+    @Deprecated
+    @Override
+    public List<Runnable> shutdownNow() {
+        return delegate.shutdownNow();
+    }
+
+    @Override
+    public boolean isShutdown() {
+        return delegate.isShutdown();
+    }
+
+    @Override
+    public boolean isTerminated() {
+        return delegate.isTerminated();
+    }
+
+    @Override
+    public boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException {
+        return delegate.awaitTermination(timeout, unit);
+    }
+
+    @Override
+    public <T> Future<T> submit(Callable<T> task) {
+        return delegate.submit(task);
+    }
+
+    @Override
+    public <T> Future<T> submit(Runnable task, T result) {
+        return delegate.submit(task, result);
+    }
+
+    @Override
+    public Future<?> submit(Runnable task) {
+        return delegate.submit(task);
+    }
+
+    @Override
+    public <T> List<java.util.concurrent.Future<T>> invokeAll(
+            Collection<? extends Callable<T>> tasks) throws InterruptedException {
+        return delegate.invokeAll(tasks);
+    }
+
+    @Override
+    public <T> List<java.util.concurrent.Future<T>> invokeAll(
+            Collection<? extends Callable<T>> tasks, long timeout,
+            TimeUnit unit) throws InterruptedException {
+        return delegate.invokeAll(tasks, timeout, unit);
+    }
+
+    @Override
+    public <T> T invokeAny(Collection<? extends Callable<T>> tasks)
+            throws InterruptedException, ExecutionException {
+        return delegate.invokeAny(tasks);
+    }
+
+    @Override
+    public <T> T invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)
+            throws InterruptedException, ExecutionException, TimeoutException {
+        return delegate.invokeAny(tasks, timeout, unit);
+    }
+
+    @Override
+    public ScheduledFuture<?> schedule(Runnable command, long delay, TimeUnit unit) {
+        return delegate.schedule(command, delay, unit);
+    }
+
+    @Override
+    public <V> ScheduledFuture<V> schedule(Callable<V> callable, long delay, TimeUnit unit) {
+        return delegate.schedule(callable, delay, unit);
+    }
+
+    @Override
+    public ScheduledFuture<?> scheduleAtFixedRate(Runnable command, long initialDelay,
+                                                   long period, TimeUnit unit) {
+        return delegate.scheduleAtFixedRate(command, initialDelay, period, unit);
+    }
+
+    @Override
+    public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command, long initialDelay,
+                                                      long delay, TimeUnit unit) {
+        return delegate.scheduleWithFixedDelay(command, initialDelay, delay, unit);
+    }
+
+    @Override
+    public void execute(Runnable command) {
+        delegate.execute(command);
+    }
+}

core/src/main/java/com/linecorp/armeria/common/util/EventLoopGroupBuilder.java

@@ -0,0 +1,151 @@
+/*
+ * Copyright 2026 LINE Corporation
+ *
+ * LINE Corporation licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+package com.linecorp.armeria.common.util;
+
+import static com.google.common.base.Preconditions.checkArgument;
+import static java.util.Objects.requireNonNull;
+
+import java.time.Duration;
+import java.util.concurrent.ThreadFactory;
+
+import com.linecorp.armeria.common.Flags;
+import com.linecorp.armeria.common.annotation.Nullable;
+import com.linecorp.armeria.common.annotation.UnstableApi;
+
+import io.netty.channel.EventLoopGroup;
+
+/**
+ * A builder for creating an {@link EventLoopGroup} with custom configuration.
+ *
+ * <h2>Example</h2>
+ * <pre>{@code
+ * EventLoopGroup eventLoopGroup = EventLoopGroups
+ *     .builder()
+ *     .numThreads(4)
+ *     .threadFactory(ThreadFactories.newThreadFactory("my-eventloop", true))
+ *     .gracefulShutdown(Duration.ofSeconds(2), Duration.ofSeconds(15))
+ *     .build();
+ * }</pre>
+ *
+ * @see EventLoopGroups#builder()
+ */
+@UnstableApi
+public final class EventLoopGroupBuilder {
+
+    public static final String DEFAULT_ARMERIA_THREAD_NAME_PREFIX = "armeria-eventloop";
+
+    // Netty defaults from AbstractEventExecutorGroup.shutdownGracefully()
+    private static final long DEFAULT_SHUTDOWN_QUIET_PERIOD_MILLIS = 2000;
+    private static final long DEFAULT_SHUTDOWN_TIMEOUT_MILLIS = 15000;
+
+    private int numThreads = Flags.numCommonWorkers();
+    @Nullable
+    private ThreadFactory threadFactory;
+    private long shutdownQuietPeriodMillis = DEFAULT_SHUTDOWN_QUIET_PERIOD_MILLIS;
+    private long shutdownTimeoutMillis = DEFAULT_SHUTDOWN_TIMEOUT_MILLIS;
+
+    EventLoopGroupBuilder() {}
+
+    /**
+     * Sets the number of event loop threads. The default is {@link Flags#numCommonWorkers()},
+     * which is typically the number of available processors multiplied by 2.
+     *
+     * @param numThreads the number of threads (must be greater than 0)
+     */
+    public EventLoopGroupBuilder numThreads(int numThreads) {
+        checkArgument(numThreads > 0, "numThreads: %s (expected: > 0)", numThreads);
+        this.numThreads = numThreads;
+        return this;
+    }
+
+    /**
+     * Sets a custom {@link ThreadFactory} for creating event loop threads.
+     *
+     * @param threadFactory the thread factory to use
+     * @see ThreadFactories for convenient factory methods to create a {@link ThreadFactory}
+     */
+    public EventLoopGroupBuilder threadFactory(ThreadFactory threadFactory) {
+        this.threadFactory = requireNonNull(threadFactory, "threadFactory");
+        return this;
+    }
+
+    /**
+     * Sets the graceful shutdown quiet period and timeout.
+     * The quiet period is the amount of time the executor will wait for new tasks before
+     * starting to shut down. The timeout is the maximum amount of time to wait for the
+     * executor to terminate.
+     *
+     * <p>The default values are 2 seconds for quiet period and 15 seconds for timeout,
+     * which are Netty's default values.
+     *
+     * @param quietPeriod the quiet period during which the executor will wait for new tasks
+     * @param timeout the maximum time to wait for the executor to terminate
+     */
+    public EventLoopGroupBuilder gracefulShutdown(Duration quietPeriod, Duration timeout) {
+        requireNonNull(quietPeriod, "quietPeriod");
+        requireNonNull(timeout, "timeout");
+        return gracefulShutdownMillis(quietPeriod.toMillis(), timeout.toMillis());
+    }
+
+    /**
+     * Sets the graceful shutdown quiet period and timeout in milliseconds.
+     * The quiet period is the amount of time the executor will wait for new tasks before
+     * starting to shut down. The timeout is the maximum amount of time to wait for the
+     * executor to terminate.
+     *
+     * <p>The default values are 2000ms for quiet period and 15000ms for timeout,
+     * which are Netty's default values.
+     *
+     * @param quietPeriodMillis the quiet period in milliseconds (must be &gt;= 0)
+     * @param timeoutMillis the timeout in milliseconds (must be &gt;= quietPeriodMillis)
+     */
+    public EventLoopGroupBuilder gracefulShutdownMillis(long quietPeriodMillis, long timeoutMillis) {
+        checkArgument(quietPeriodMillis >= 0,
+                      "quietPeriodMillis: %s (expected: >= 0)", quietPeriodMillis);
+        checkArgument(timeoutMillis >= quietPeriodMillis,
+                      "timeoutMillis: %s (expected: >= quietPeriodMillis)", timeoutMillis);
+        shutdownQuietPeriodMillis = quietPeriodMillis;
+        shutdownTimeoutMillis = timeoutMillis;
+        return this;
+    }
+
+    /**
+     * Returns a newly-created {@link EventLoopGroup} with the properties set on this builder.
+     * If graceful shutdown parameters have been configured, the returned {@link EventLoopGroup}
+     * will use those parameters when {@link EventLoopGroup#shutdownGracefully()} is called.
+     */
+    public EventLoopGroup build() {
+        final TransportType type = Flags.transportType();
+        final ThreadFactory factory;
+        if (threadFactory != null) {
+            factory = threadFactory;
+        } else {
+            final String prefix = DEFAULT_ARMERIA_THREAD_NAME_PREFIX + '-' + type.lowerCasedName();
+            factory = ThreadFactories.newEventLoopThreadFactory(prefix, false);
+        }
+
+        final EventLoopGroup eventLoopGroup = type.newEventLoopGroup(numThreads, unused -> factory);
+
+        // Wrap with shutdown configuration if non-default values are used
+        if (shutdownQuietPeriodMillis != DEFAULT_SHUTDOWN_QUIET_PERIOD_MILLIS ||
+            shutdownTimeoutMillis != DEFAULT_SHUTDOWN_TIMEOUT_MILLIS) {
+            return new ShutdownConfigurableEventLoopGroup(
+                    eventLoopGroup, shutdownQuietPeriodMillis, shutdownTimeoutMillis);
+        }
+        return eventLoopGroup;
+    }
+}