-
-
Notifications
You must be signed in to change notification settings - Fork 15.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add service-loaded extension points for channel initialization (#13565)
**Motivation:** Netty is used by many libraries and frameworks that (reasonably) hide the fact that they use Netty under the covers. When Netty is hidden, it is hard, or sometimes impossible, to modify the channel pipelines, attributes, or options, from the outside. It might not even be clear if a framework or library makes use of Netty at all. However, we sometimes want to apply some changes, or make some checks, to most or all channels that are initialized by Netty, regardless of the framework or library that is using Netty in the given case. Some examples of use-cases are: - Web application firewalls. - Server-side request forgery filters. - Intrusion detection. - Metrics gathering. To address these use-cases in a way that don't require integrators to somehow find every Netty usage in a process, we introduce a service-loaded extension point that hooks into the channel initialization process. **Modification:** A new abstract class, `ChannelInitializerExtension`, is added. Implementations of this interface can be found and service-loaded at runtime by `AbstractBootstrap`, with the help of the `ChannelInitializerExtensions` utility class. The `ChannelInitializerExtension` class offers three callback methods, one for the initialization of each of the different "kinds" of channels: - Server listener channels. - Server child channels. - Client channels. The extensions are disabled by default for security reasons, and require opt in by setting the `io.netty.bootstrap.extensions` system property to `serviceload`. To see what extensions are available, the system property can be set to `log`, and we will load and log (at INFO level) what extensions are available, but not actually run them. **Result:** We have extension points for use cases that are cutting-across different Netty uses, and require low-level Netty access. This makes it relatively easy to implement such use cases without requiring deep access to the Netty internals of arbitrary libraries and frameworks, and without even needing to know which libraries and frameworks are actually using Netty. The only restriction to this, is the use of shading with class-relocation, which in each case would require their own `META-INF/services` file. Thankfully, most libraries and frameworks that shade Netty, also offer non-shading versions.
- Loading branch information
Showing
13 changed files
with
463 additions
and
19 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
122 changes: 122 additions & 0 deletions
122
transport/src/main/java/io/netty/bootstrap/ChannelInitializerExtension.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| /* | ||
| * Copyright 2023 The Netty Project | ||
| * | ||
| * The Netty Project 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 io.netty.bootstrap; | ||
|
|
||
| import io.netty.channel.Channel; | ||
| import io.netty.channel.ServerChannel; | ||
|
|
||
| /** | ||
| * A channel initializer extension make it possible to enforce rules and apply modifications across multiple, | ||
| * disconnected uses of Netty within the same JVM process. | ||
| * <p> | ||
| * For instance, application-level firewall rules can be injected into all uses of Netty within an application, | ||
| * without making changes to such uses that are otherwise outside the purview of the application code, | ||
| * such as 3rd-party libraries. | ||
| * <p> | ||
| * Channel initializer extensions are <em>not</em> enabled by default, because of their power to influence Netty | ||
| * pipelines across libraries, frameworks, and use-cases. | ||
| * Extensions must be explicitly enabled by setting the {@value #EXTENSIONS_SYSTEM_PROPERTY} to {@code serviceload}. | ||
| * <p> | ||
| * All channel initializer extensions that are available on the classpath will be | ||
| * {@linkplain java.util.ServiceLoader#load(Class) service-loaded} and used by all {@link AbstractBootstrap} subclasses. | ||
| * <p> | ||
| * Note that this feature will not work for Netty uses that are shaded <em>and relocated</em> into other libraries. | ||
| * The classes in a relocated Netty library are technically distinct and incompatible types. This means the | ||
| * service-loader in non-relocated Netty will not see types from a relocated Netty, and vice versa. | ||
| */ | ||
| public abstract class ChannelInitializerExtension { | ||
| /** | ||
| * The name of the system property that control initializer extensions. | ||
| * <p> | ||
| * These extensions can potentially be a security liability, so they are disabled by default. | ||
| * <p> | ||
| * To enable the extensions, application operators can explicitly opt in by setting this system property to the | ||
| * value {@code serviceload}. This will enable all the extensions that are available through the service loader | ||
| * mechanism. | ||
| * <p> | ||
| * To load and log (at INFO level) all available extensions without actually running them, set this system property | ||
| * to the value {@code log}. | ||
| */ | ||
| public static final String EXTENSIONS_SYSTEM_PROPERTY = "io.netty.bootstrap.extensions"; | ||
|
|
||
| /** | ||
| * Get the "priority" of this extension. If multiple extensions are avilable, then they will be called in their | ||
| * priority order, from lowest to highest. | ||
| * <p> | ||
| * Implementers are encouraged to pick a number between {@code -100.0} and {@code 100.0}, where extensions that have | ||
| * no particular opinion on their priority are encouraged to return {@code 0.0}. | ||
| * <p> | ||
| * Extensions with lower priority will get called first, while extensions with greater priority may be able to | ||
| * observe the effects of extensions with lesser priority. | ||
| * <p> | ||
| * Note that if multiple extensions have the same priority, then their relative order will be unpredictable. | ||
| * As such, implementations should always take into consideration that other extensions might be called before | ||
| * or after them. | ||
| * <p> | ||
| * Override this method to specify your own priority. | ||
| * The default implementation just returns {@code 0}. | ||
| * | ||
| * @return The priority. | ||
| */ | ||
| public double priority() { | ||
| return 0; | ||
| } | ||
|
|
||
| /** | ||
| * Called by {@link Bootstrap} after the initialization of the given client channel. | ||
| * <p> | ||
| * The method is allowed to modify the handlers in the pipeline, the channel attributes, or the channel options. | ||
| * The method must refrain from doing any I/O, or from closing the channel. | ||
| * <p> | ||
| * Override this method to add your own callback logic. | ||
| * The default implementation does nothing. | ||
| * | ||
| * @param channel The channel that was initialized. | ||
| */ | ||
| public void postInitializeClientChannel(Channel channel) { | ||
| } | ||
|
|
||
| /** | ||
| * Called by {@link ServerBootstrap} after the initialization of the given server listener channel. | ||
| * The listener channel is responsible for invoking the {@code accept(2)} system call, | ||
| * and for producing child channels. | ||
| * <p> | ||
| * The method is allowed to modify the handlers in the pipeline, the channel attributes, or the channel options. | ||
| * The method must refrain from doing any I/O, or from closing the channel. | ||
| * <p> | ||
| * Override this method to add your own callback logic. | ||
| * The default implementation does nothing. | ||
| * | ||
| * @param channel The channel that was initialized. | ||
| */ | ||
| public void postInitializeServerListenerChannel(ServerChannel channel) { | ||
| } | ||
|
|
||
| /** | ||
| * Called by {@link ServerBootstrap} after the initialization of the given child channel. | ||
| * A child channel is a newly established connection from a client to the server. | ||
| * <p> | ||
| * The method is allowed to modify the handlers in the pipeline, the channel attributes, or the channel options. | ||
| * The method must refrain from doing any I/O, or from closing the channel. | ||
| * <p> | ||
| * Override this method to add your own callback logic. | ||
| * The default implementation does nothing. | ||
| * | ||
| * @param channel The channel that was initialized. | ||
| */ | ||
| public void postInitializeServerChildChannel(Channel channel) { | ||
| } | ||
| } |
Oops, something went wrong.