Generalize the httpAuthentication infrastructure and remove SPNEGO-specific design

Following the review feedback, this change updates the proposed SPNEGO-specific
implementation into a more generic authentication flow that can support various
HTTP authentication mechanisms.

Signed-off-by: raccoonback <[email protected]>

Author: raccoonback

CLAUDE.md

@@ -0,0 +1,83 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Reactor-Netty is a reactive networking library providing non-blocking TCP/HTTP/UDP/QUIC clients and servers based on Netty. It's part of the Project Reactor ecosystem and requires Java 8+ to run.
+
+## Build System
+
+**Gradle-based** multi-module project using Gradle 8.14.2:
+
+```bash
+# Build and test
+./gradlew build                    # Build all modules
+./gradlew check                    # Run all checks including tests
+./gradlew test                     # Run tests
+./gradlew clean                    # Clean build artifacts
+
+# Module-specific testing
+./gradlew reactor-netty-core:test  # Test core module
+./gradlew reactor-netty-http:test  # Test HTTP module
+
+# Code quality
+./gradlew spotlessCheck           # Check code formatting
+./gradlew spotlessApply           # Apply code formatting
+./gradlew checkstyle              # Run checkstyle
+
+# Documentation
+./gradlew javadoc                 # Generate Javadoc
+./gradlew antora                  # Build Antora documentation
+
+# Publishing
+./gradlew publishToMavenLocal     # Publish to local Maven repository
+```
+
+## Architecture
+
+### Core Modules
+
+- **`reactor-netty-core`**: Core networking functionality, connection management, metrics
+- **`reactor-netty-http`**: HTTP client/server with HTTP/2 and HTTP/3 support
+- **`reactor-netty-http-brave`**: Brave tracing integration
+- **`reactor-netty-incubator-quic`**: QUIC protocol support (experimental)
+- **`reactor-netty-examples`**: Example applications
+
+### Key Source Structure
+
+**reactor-netty-core/src/main/java/reactor/netty/**:
+- **Core APIs**: `Connection`, `ByteBufFlux`, `ByteBufMono`, `ReactorNetty`
+- **channel/**: Channel operations, metrics, observations
+- **resources/**: Connection providers, event loops, pooling
+- **tcp/**: TCP client/server implementations and SSL support
+- **transport/**: Transport abstractions, address resolution, logging
+- **udp/**: UDP client/server implementations
+
+**reactor-netty-http/src/main/java/reactor/netty/http/**:
+- **client/**: HTTP client with HTTP/2, HTTP/3, WebSocket support
+- **server/**: HTTP server with routing, compression, observability
+- **websocket/**: WebSocket client/server functionality
+
+## Testing
+
+Multiple test sourcesets for comprehensive coverage:
+- **Regular tests**: `src/test/java/`
+- **Context propagation tests**: `src/contextPropagationTest/`
+- **HTTP/3 tests**: `src/http3Test/`
+- **No-micrometer tests**: `src/noMicrometerTest/`
+
+## Key Technologies
+
+- **Netty 4.1.122.Final**: Core networking framework
+- **Project Reactor 3.7.8-SNAPSHOT**: Reactive streams
+- **Micrometer 1.14.0**: Metrics and observability
+- **Multi-release JARs**: Java 8/17 compatibility using `me.champeau.mrjar` plugin
+
+## Development Notes
+
+- Uses **shadowed JARs** in core module for dependency isolation
+- **Native transports**: Epoll (Linux), KQueue (macOS), io_uring (Linux)
+- **Observability**: Comprehensive metrics, tracing, and context propagation
+- **API compatibility**: JAPICMP checks for API compatibility
+- **Documentation**: Antora-based AsciiDoc documentation in `/docs/`

docs/modules/ROOT/pages/http-client.adoc

@@ -743,143 +743,105 @@ include::{examples-dir}/resolver/Application.java[lines=18..39]
 ----
 <1> The timeout of each DNS query performed by this resolver will be 500ms.
 
-[[http-client-spnego]]
-== SPNEGO Authentication
-Reactor Netty HttpClient supports SPNEGO (Kerberos) authentication, which is widely used in enterprise environments.
-SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) provides secure authentication over HTTP using Kerberos.
+[[http-authentication]]
+== HTTP Authentication
+Reactor Netty `HttpClient` provides a flexible HTTP authentication framework that allows you to implement
+custom authentication mechanisms such as SPNEGO/Negotiate, OAuth, Bearer tokens, or any other HTTP-based authentication scheme.
 
-==== How It Works
-SPNEGO authentication follows this HTTP authentication flow:
+The {javadoc}/reactor/netty/http/client/HttpClient.html#httpAuthentication-java.util.function.BiPredicate-java.util.function.BiFunction-[`httpAuthentication`]
+method accepts two parameters:
 
-. The client sends an HTTP request to a protected resource.
-. The server responds with `401 Unauthorized` and a `WWW-Authenticate: Negotiate` header.
-. The client generates a SPNEGO token based on its Kerberos ticket, and resends the request with an `Authorization: Negotiate <base64-encoded-token>` header.
-. The server validates the token and, if authentication is successful, returns 200 OK.
-
-If further negotiation is required, the server may return another 401 with additional data in the `WWW-Authenticate` header.
+* A predicate that determines when authentication should be applied (typically by checking the HTTP status code and headers)
+* An authenticator function that applies authentication credentials to the request
 
-==== JAAS-based Authenticator
-{examples-link}/spnego/jaas/Application.java
-----
-include::{examples-dir}/spnego/jaas/Application.java[lines=18..45]
-----
-<1> Configures the `jaas.conf`. A JAAS configuration file in Java for integrating with authentication backends such as Kerberos.
-<2> Configures the `krb5.conf`. krb5.conf is a Kerberos client configuration file used to define how the client locates and communicates with the Kerberos Key Distribution Center (KDC) for authentication.
-<3> Configures the SPNEGO jaas.conf. A JVM system property that enables detailed debug logging for Kerberos operations in Java.
-<4> `JaasAuthenticator` performs Kerberos authentication using a JAAS configuration (jaas.conf).
-<5> `SpnegoAuthProvider.Builder` supports the following configuration methods. Please refer to <<spnegoauthprovider-config>>.
-<6> `SpnegoAuthProvider`  generates a SPNEGO token from the Kerberos ticket. It automatically adds the `Authorization: Negotiate ...` header to HTTP requests. If the server responds with `401 Unauthorized` and includes `WWW-Authenticate: Negotiate`, the client will automatically reauthenticate and retry the request once.
+This approach gives you complete control over the authentication flow while Reactor Netty handles the retry mechanism.
 
-===== Example JAAS Configuration
-Specify the path to your JAAS configuration file using the `java.security.auth.login.config` system property.
-
-.`jaas.conf`
-[jaas,conf]
-----
-KerberosLogin {
-    com.sun.security.auth.module.Krb5LoginModule required
-    client=true
-    useKeyTab=true
-    keyTab="/path/to/test.keytab"
-    principal="[email protected]"
-    doNotPrompt=true
-    debug=true;
-};
-----
+=== How It Works
 
-===== Example Kerberos Configuration
-Specify Kerberos realm and KDC information using the `java.security.krb5.conf` system property.
+The typical HTTP authentication flow works as follows:
 
-.`krb5.conf`
-[krb5,conf]
-----
-[libdefaults]
-    default_realm = EXAMPLE.COM
-[realms]
-    EXAMPLE.COM = {
-        kdc = kdc.example.com
-    }
-[domain_realms]
-    .example.com = EXAMPLE.COM
-    example.com = EXAMPLE.COM
-----
+. The client sends an HTTP request to a protected resource.
+. The server responds with an authentication challenge (e.g., `401 Unauthorized` with a `WWW-Authenticate` header).
+. The authenticator function is invoked to add authentication credentials to the request.
+. The request is retried with the authentication credentials.
+. If authentication is successful, the server returns the requested resource.
 
-===== Configuration Example
-[jvm option]
-----
--Djava.security.auth.login.config=/path/to/login.conf
--Djava.security.krb5.conf=/path/to/krb5.conf
-----
+=== Token-Based Authentication Example
 
-==== GSSCredential-based Authenticator
-For scenarios where you already have a `GSSCredential` available or want to avoid JAAS configuration, you can use `GssCredentialAuthenticator`:
+The following example demonstrates how to implement Bearer token authentication:
 
-{examples-link}/spnego/gsscredential/Application.java
+{examples-link}/authentication/token/Application.java
+[%unbreakable]
 ----
-include::{examples-dir}/spnego/gsscredential/Application.java[lines=18..46]
+include::{examples-dir}/authentication/token/Application.java[lines=18..52]
 ----
-<1> Obtain the `GSSCredential` through other means.
-<2> Configure the GSSCredential-based authenticator for SPNEGO authentication.
+<1> The predicate checks if the response status is `401 Unauthorized`.
+<2> The authenticator adds the `Authorization` header with a Bearer token.
 
-This approach is useful when:
-- You want to reuse existing credentials
-- You need more control over credential management
-- JAAS configuration is not available or preferred
+=== SPNEGO/Negotiate Authentication Example
 
-==== Custom Authenticator Implementation
-For advanced scenarios where the provided authenticators don't meet your specific requirements, you can implement the `SpnegoAuthenticator` interface directly:
+For SPNEGO (Kerberos) authentication, you can implement a custom authenticator using Java's GSS-API:
 
+{examples-link}/authentication/spnego/Application.java
+[%unbreakable]
+----
+include::{examples-dir}/authentication/spnego/Application.java[lines=18..69]
 ----
-import org.ietf.jgss.GSSContext;
-import reactor.netty.http.client.SpnegoAuthenticator;
-import reactor.netty.http.client.SpnegoAuthProvider;
+<1> The predicate checks for `401 Unauthorized` with `WWW-Authenticate: Negotiate` header.
+<2> The authenticator generates a SPNEGO token using GSS-API and adds it to the `Authorization` header.
 
-public class CustomSpnegoAuthenticator implements SpnegoAuthenticator {
+NOTE: For SPNEGO authentication, you need to configure Kerberos settings (e.g., `krb5.conf`) and JAAS configuration
+(e.g., `jaas.conf`) appropriately. Set the system properties `java.security.krb5.conf` and `java.security.auth.login.config`
+to point to your configuration files.
 
-    @Override
-    public GSSContext createContext(String serviceName, String remoteHost) throws Exception {
-        // Your custom authentication logic here
-        // This method should return a configured GSSContext
-        // for the specified service and remote host
-        // serviceName: e.g., "HTTP", "LDAP"
-        // remoteHost: target server hostname
+=== Custom Authentication Scenarios
 
-        return null; // Replace with actual GSSContext creation logic
-    }
-}
+The `httpAuthentication` method is flexible enough to support various authentication scenarios:
 
-// Usage with advanced configuration
+==== OAuth 2.0 Authentication
+[source,java]
+----
 HttpClient client = HttpClient.create()
-	.spnego(
-		SpnegoAuthProvider.builder(new CustomSpnegoAuthenticator())
-			.serviceName("HTTP")  // Custom service name
-			.unauthorizedStatusCode(401)  // Custom status code
-			.resolveCanonicalHostname(true)  // Use canonical hostname
-			.build()
-	);
+    .httpAuthentication(
+        (req, res) -> res.status().code() == 401,
+        (req, addr) -> {
+            return fetchOAuthToken() // <1>
+                .doOnNext(token ->
+                    req.header(HttpHeaderNames.AUTHORIZATION, "Bearer " + token))
+                .then();
+        }
+    );
+----
+<1> Asynchronously fetch an OAuth token and add it to the request.
+
+==== Basic Authentication
+{examples-link}/authentication/basic/Application.java
+[%unbreakable]
 ----
+include::{examples-dir}/authentication/basic/Application.java[lines=18..46]
+----
+<1> The predicate checks if the response status is `401 Unauthorized`.
+<2> The authenticator adds Basic authentication credentials to the `Authorization` header.
 
-This approach is useful when you need:
-- Custom credential acquisition logic
-- Integration with third-party authentication systems
-- Special handling for token caching or refresh
-- Environment-specific authentication flows
-
-[[spnegoauthprovider-config]]
-==== SpnegoAuthProvider Configuration Options
-The `SpnegoAuthProvider.Builder` supports the following configuration Options:
-
-[width="100%",options="header"]
-|=======
-| Method | Default | Description | Example
-| `serviceName(String)` | "HTTP" | Service name for constructing service principal names (serviceName/hostname) | "HTTP", "LDAP"
-| `unauthorizedStatusCode(int)` | 401 | HTTP status code that triggers authentication retry | 401, 407
-| `resolveCanonicalHostname(boolean)` | false | Whether to use canonical hostname resolution via reverse DNS lookup | true for FQDN requirements
-|=======
-
-==== Notes
-- SPNEGO authentication is fully supported on Java 1.6 and above.
-- If authentication fails, check the server logs and client exception messages, and verify your Kerberos environment settings (realm, KDC, ticket, etc.).
-- `JaasAuthenticator` performs authentication through JAAS login configuration.
-- `GssCredentialAuthenticator` uses pre-existing `GSSCredential` objects, bypassing JAAS configuration.
-- For custom scenarios, implement the `SpnegoAuthenticator` interface to provide your own authentication logic.
+==== Proxy Authentication
+[source,java]
+----
+HttpClient client = HttpClient.create()
+    .httpAuthentication(
+        (req, res) -> res.status().code() == 407, // <1>
+        (req, addr) -> {
+            String proxyCredentials = generateProxyCredentials();
+            req.header("Proxy-Authorization", "Bearer " + proxyCredentials);
+            return Mono.empty();
+        }
+    );
+----
+<1> Check for `407 Proxy Authentication Required` status code.
+
+=== Important Notes
+
+* The authenticator function is invoked only when the predicate returns `true`.
+* The authenticator receives the request and remote address, allowing you to customize authentication based on the target server.
+* The authenticator returns a `Mono<Void>` which allows for asynchronous credential retrieval.
+* Authentication is retried only once per request. If authentication fails after retry, the error is propagated to the caller.
+* For security reasons, ensure that sensitive credentials are not logged or exposed in error messages.

reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/http/client/authentication/basic/Application.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025 VMware, Inc. or its affiliates, All Rights Reserved.
+ *
+ * Licensed 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 reactor.netty.examples.documentation.http.client.authentication.basic;
+
+import io.netty.handler.codec.http.HttpHeaderNames;
+import reactor.core.publisher.Mono;
+import reactor.netty.http.client.HttpClient;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+
+public class Application {
+
+	public static void main(String[] args) {
+		HttpClient client =
+				HttpClient.create()
+				          .httpAuthentication(
+				              (req, res) -> res.status().code() == 401, // <1>
+				              (req, addr) -> { // <2>
+				                  String credentials = "username:password";
+				                  String encodedCredentials = Base64.getEncoder()
+				                      .encodeToString(credentials.getBytes(StandardCharsets.UTF_8));
+				                  req.header(HttpHeaderNames.AUTHORIZATION, "Basic " + encodedCredentials);
+				                  return Mono.empty();
+				              }
+				          );
+
+		client.get()
+		      .uri("https://example.com/")
+		      .response()
+		      .block();
+	}
+}