Introduce ServerPlugin (#6825)

Motivation:

When integrating cross-cutting server concerns (e.g., xDS-driven TLS,
service decorators, server listeners), users currently need to call
multiple `ServerBuilder` methods individually. There's no way to bundle
these concerns into a reusable unit that also participates in
`Server.reconfigure()` and gets cleaned up on server stop.

Modifications:

- Added `ServerPlugin` interface (extends `SafeCloseable`) with a single
`install(ServerBuilder)` method.
- Added `ServerBuilder.plugin(ServerPlugin)` to register plugins at
build time.
- In `ServerBuilder.build()`, call `plugin.install(this)` for each
registered plugin before building the server config.
- In `Server.reconfigure()`, re-install all plugins on the new
`ServerBuilder` after the `ServerConfigurator` runs.
- In `Server.finishDoStop()`, close plugins via the existing
`ShutdownSupport` machinery.
- Added `ServerPluginTest` covering install-on-build,
install-on-reconfigure, close-on-stop, ordering, and builder
modification.

Result:

- Users can encapsulate multi-concern server configuration into a single
`ServerPlugin` and register it with `ServerBuilder.plugin(plugin)`.
- Plugins are automatically re-installed during `Server.reconfigure()`
and closed when the server stops.

Author: jrhee17

core/src/main/java/com/linecorp/armeria/server/Server.java

@@ -113,17 +113,19 @@ public static ServerBuilder builder() {
     @GuardedBy("lock")
     private final Map<InetSocketAddress, ServerPort> activePorts = new LinkedHashMap<>();
     private final ConnectionLimitingHandler connectionLimitingHandler;
+    private final List<ServerPlugin> plugins;
     private boolean hasWebSocketService;
 
     @Nullable
     @VisibleForTesting
     ServerBootstrap serverBootstrap;
 
-    Server(DefaultServerConfig serverConfig) {
+    Server(DefaultServerConfig serverConfig, List<ServerPlugin> plugins) {
         serverConfig.setServer(this);
         config = new UpdatableServerConfig(requireNonNull(serverConfig, "serverConfig"));
         startStop = new ServerStartStopSupport(config.startStopExecutor());
         connectionLimitingHandler = new ConnectionLimitingHandler(config.maxNumConnections());
+        this.plugins = requireNonNull(plugins, "plugins");
 
         // Server-wide metrics.
         RequestTargetCache.registerServerMetrics(config.meterRegistry());
@@ -418,6 +420,7 @@ public void reconfigure(ServerConfigurator serverConfigurator) {
         requireNonNull(serverConfigurator, "serverConfigurator");
         final ServerBuilder sb = builder();
         serverConfigurator.reconfigure(sb);
+        plugins.forEach(plugin -> plugin.install(sb));
         final ImmutableList<ServerPort> serverPorts;
         lock.lock();
         try {
@@ -720,6 +723,9 @@ private void finishDoStop(CompletableFuture<Void> future) {
             serverChannels.clear();
 
             final Builder<ShutdownSupport> builder = ImmutableList.builder();
+            for (ServerPlugin plugin : plugins) {
+                builder.add(ShutdownSupport.of(plugin));
+            }
             builder.addAll(config.delegate().shutdownSupports());
             for (VirtualHost virtualHost : config.virtualHosts()) {
                 builder.addAll(virtualHost.shutdownSupports());

core/src/main/java/com/linecorp/armeria/server/ServerBuilder.java

@@ -44,10 +44,12 @@
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.Comparator;
 import java.util.List;
 import java.util.Map;
 import java.util.Map.Entry;
 import java.util.Optional;
+import java.util.ServiceLoader;
 import java.util.concurrent.Executor;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
@@ -245,6 +247,9 @@ public final class ServerBuilder implements TlsSetters, ServiceConfigsBuilder<Se
     private final ServerTlsProviderBuilder serverTlsProviderBuilder = new ServerTlsProviderBuilder();
     private Function<? super String, ? extends EventLoopGroup> bossGroupFactory = DEFAULT_BOSS_GROUP_FACTORY;
     private ConnectionAcceptor connectionAcceptor = ConnectionAcceptor.always();
+    private static final List<ServerPlugin> SPI_PLUGINS =
+            ImmutableList.copyOf(ServiceLoader.load(ServerPlugin.class));
+    private final List<ServerPlugin> plugins = new ArrayList<>();
 
     ServerBuilder() {
         // Set the default host-level properties.
@@ -532,6 +537,25 @@ public ServerBuilder connectionAcceptor(ConnectionAcceptor connectionAcceptor) {
         return this;
     }
 
+    /**
+     * Adds a {@link ServerPlugin} that will be installed during {@link Server} construction
+     * and during {@link Server#reconfigure(ServerConfigurator)}.
+     *
+     * <p>Plugins are installed in insertion order. Each plugin's
+     * {@link ServerPlugin#install(ServerBuilder)} is called before the server configuration
+     * is built. Plugins are closed when the {@link Server} stops.
+     *
+     * <p>Note: Plugins can only be added at initial build time. Calling
+     * {@link ServerBuilder#plugin(ServerPlugin)} inside a {@link ServerConfigurator} passed to
+     * {@link Server#reconfigure(ServerConfigurator)} has no effect — the server uses the plugins
+     * registered at construction. Existing plugins are re-installed automatically during reconfiguration.
+     */
+    @UnstableApi
+    public ServerBuilder plugin(ServerPlugin plugin) {
+        plugins.add(requireNonNull(plugin, "plugin"));
+        return this;
+    }
+
     /**
      * Sets the worker {@link EventLoopGroup} which is responsible for performing socket I/O and running
      * {@link Service#serve(ServiceRequestContext, Request)}.
@@ -2466,11 +2490,24 @@ public ServerBuilder unloggedExceptionsReportIntervalMillis(long unloggedExcepti
      * Returns a newly-created {@link Server} based on the configuration properties set so far.
      */
     public Server build() {
-        final Server server = new Server(buildServerConfig(ports));
+        final List<ServerPlugin> plugins = buildPlugins();
+        plugins.forEach(plugin -> plugin.install(this));
+        final Server server = new Server(buildServerConfig(ports), plugins);
         serverListeners.forEach(server::addListener);
         return server;
     }
 
+    private List<ServerPlugin> buildPlugins() {
+        // SPI-discovered plugins first, then user-registered plugins
+        return ImmutableList.<ServerPlugin>builder()
+                            .addAll(SPI_PLUGINS)
+                            .addAll(this.plugins)
+                            .build()
+                            .stream()
+                            .sorted(Comparator.comparingInt(ServerPlugin::order))
+                            .collect(toImmutableList());
+    }
+
     DefaultServerConfig buildServerConfig(List<ServerPort> serverPorts) {
         final AnnotatedServiceExtensions extensions =
                 virtualHostTemplate.annotatedServiceExtensions();

core/src/main/java/com/linecorp/armeria/server/ServerPlugin.java

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2026 LY Corporation
+ *
+ * LY 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.server;
+
+import com.linecorp.armeria.common.annotation.UnstableApi;
+
+/**
+ * A plugin that encapsulates multi-concern registration into a single
+ * {@link ServerBuilder#plugin(ServerPlugin)} call.
+ *
+ * <p>The {@link #install(ServerBuilder)} method is called during {@link Server} construction
+ * and during {@link Server#reconfigure(ServerConfigurator)}, allowing the plugin to register
+ * any combination of server-level concerns (e.g., ports, TLS, service decorators).
+ *
+ * <p>Plugins are sorted by {@link #order()} before installation. Lower values are installed first.
+ *
+ * <p>The {@link #close()} method is called when the {@link Server} stops, allowing the plugin
+ * to clean up resources such as subscriptions or background tasks.
+ *
+ * <h2>Example</h2>
+ * <pre>{@code
+ * Server server = Server.builder()
+ *                       .http(8080)
+ *                       .service("/", (ctx, req) -> HttpResponse.of(200))
+ *                       .plugin(sb -> sb.decorator(LoggingService.newDecorator()))
+ *                       .build();
+ * }</pre>
+ */
+@FunctionalInterface
+@UnstableApi
+public interface ServerPlugin extends AutoCloseable {
+
+    /**
+     * Installs this plugin into the given {@link ServerBuilder}. Called during
+     * {@link Server} construction and during {@link Server#reconfigure(ServerConfigurator)}.
+     */
+    void install(ServerBuilder sb);
+
+    /**
+     * Returns the order of this plugin. Plugins with lower values are installed first.
+     * Plugins with the same order preserve their insertion order (stable sort).
+     * The default value is {@code 0}.
+     */
+    default int order() {
+        return 0;
+    }
+
+    /**
+     * Called when the {@link Server} stops, allowing the plugin to clean up resources.
+     * Note that if the same plugin instance is registered with multiple servers,
+     * this method will be called once for each server that stops.
+     * The default implementation is a no-op.
+     */
+    @Override
+    default void close() {}
+}