Deprecate HttpContextKeys.HTTP_TARGET_ADDRESS_BEHIND_PROXY (#2722)

Motivation:

Prior to `ConnectionObserver.ProxyConnectObserver` added in #2711, the
sequence of `ConnectionObserver` events was different between regular
connections and connection to the proxy tunnels.
`HttpContextKeys.HTTP_TARGET_ADDRESS_BEHIND_PROXY` (#2169) was useful to
distinguish when the correct callback inside `ConnectionObserver` before
reporting that a new connection is ready to take traffic.
After adding `ProxyConnectObserver`, there is no need in this custom
key.

Modifications:

- Deprecate `HttpContextKeys.HTTP_TARGET_ADDRESS_BEHIND_PROXY` and
describe what is an appropriate replacement for users;

Result:

We will be able to remove
`HttpContextKeys.HTTP_TARGET_ADDRESS_BEHIND_PROXY` in the future
releases.

servicetalk-http-api/src/main/java/io/servicetalk/http/api/HttpContextKeys.java

@@ -15,9 +15,12 @@
  */
 package io.servicetalk.http.api;
 
+import io.servicetalk.client.api.TransportObserverConnectionFactoryFilter;
 import io.servicetalk.context.api.ContextMap;
 import io.servicetalk.context.api.ContextMap.Key;
 import io.servicetalk.transport.api.ConnectionInfo;
+import io.servicetalk.transport.api.ConnectionObserver;
+import io.servicetalk.transport.api.TransportObserver;
 
 import static io.servicetalk.context.api.ContextMap.Key.newKey;
 
@@ -43,8 +46,15 @@ public final class HttpContextKeys {
      * HTTP proxy tunneling</a> and a clear text HTTP proxy, check presence of {@link ConnectionInfo#sslConfig()}.
      *
      * @see SingleAddressHttpClientBuilder#proxyAddress(Object)
+     * @deprecated Use {@link TransportObserverConnectionFactoryFilter} to configure {@link TransportObserver} and then
+     * listen {@link ConnectionObserver#onProxyConnect(Object)} callback to distinguish between a regular connection and
+     * a connection to the secure HTTP proxy tunnel. For clear text HTTP proxies, consider installing a custom client
+     * filter that will populate {@link HttpRequestMetaData#context()} with a similar key or reach out to the
+     * ServiceTalk developers to discuss ideas.
      */
-    public static final Key<Object> HTTP_TARGET_ADDRESS_BEHIND_PROXY =
+    @Deprecated
+    @SuppressWarnings("DeprecatedIsStillUsed")
+    public static final Key<Object> HTTP_TARGET_ADDRESS_BEHIND_PROXY =  // FIXME: 0.43 - remove deprecated constant
             newKey("HTTP_TARGET_ADDRESS_BEHIND_PROXY", Object.class);
 
     /**

servicetalk-http-netty/src/main/java/io/servicetalk/http/netty/AbsoluteAddressHttpRequesterFilter.java

@@ -89,6 +89,7 @@ public HttpExecutionStrategy requiredOffloads() {
         return HttpExecutionStrategies.offloadNone();
     }
 
+    @SuppressWarnings("deprecation")
     private Single<StreamingHttpResponse> request(final StreamingHttpRequester delegate,
                                                   final StreamingHttpRequest request) {
         return defer(() -> {

servicetalk-http-netty/src/main/java/io/servicetalk/http/netty/DefaultSingleAddressHttpClientBuilder.java

@@ -241,6 +241,7 @@ public HttpExecutionStrategy executionStrategy() {
 
             if (roConfig.hasProxy() && sslContext != null) {
                 assert roConfig.connectAddress() != null;
+                @SuppressWarnings("deprecation")
                 final ConnectionFactoryFilter<R, FilterableStreamingHttpConnection> proxy =
                         new ProxyConnectConnectionFactoryFilter<>(roConfig.connectAddress(), connectionFactoryStrategy);
                 assert !proxy.requiredOffloads().hasOffloads();

servicetalk-http-netty/src/main/java/io/servicetalk/http/netty/ProxyConnectConnectionFactoryFilter.java

@@ -46,7 +46,10 @@
  *
  * @param <ResolvedAddress> The type of resolved addresses that can be used for connecting.
  * @param <C> The type of connections created by this factory.
+ * @deprecated This filter won't be required after {@link HttpContextKeys#HTTP_TARGET_ADDRESS_BEHIND_PROXY} is removed.
  */
+@Deprecated // FIXME: 0.43 - remove deprecated class
+@SuppressWarnings("DeprecatedIsStillUsed")
 final class ProxyConnectConnectionFactoryFilter<ResolvedAddress, C extends FilterableStreamingHttpConnection>
         implements ConnectionFactoryFilter<ResolvedAddress, C> {
 
@@ -70,6 +73,7 @@ private ProxyFilter(final ConnectionFactory<ResolvedAddress, C> delegate) {
         }
 
         @Override
+        @SuppressWarnings("deprecation")
         public Single<C> newConnection(final ResolvedAddress resolvedAddress,
                                        @Nullable ContextMap context,
                                        @Nullable final TransportObserver observer) {
@@ -84,6 +88,7 @@ public Single<C> newConnection(final ResolvedAddress resolvedAddress,
         }
     }
 
+    @SuppressWarnings("deprecation")
     static void logUnexpectedAddress(@Nullable final Object current, final Object expected, final Logger logger) {
         if (current != null && !expected.equals(current)) {
             logger.info("Observed unexpected value for {}: {}, overridden with: {}",