GH-5723: propagate maxExecutionTime as per-request HTTP response timeout

When setMaxExecutionTime(int) is called on an HTTP-based query or
update, the value is now applied as a per-request response timeout on
the HTTP connection, enforced client-side in addition to being sent as a
server-sidehint.

HttpRequest gains an optional responseTimeout field (Duration). Both
SPARQLProtocolSession and RDF4JProtocolSession (which overrides
getQueryMethod/getUpdateMethod) set this field when maxQueryTime > 0.
The Apache HC5 client applies it via RequestConfig#setResponseTimeout,
overriding the client-level socket timeout for that specific request.
The JDK client applies it via HttpRequest.Builder#timeout, with the
per-request value taking precedence over the global socketTimeoutMs
from RDF4JHttpClientConfig.

Author: aschwarte10

core/http/client-apache5/src/main/java/org/eclipse/rdf4j/http/client/apache5/ApacheHC5RDF4JHttpClient.java

@@ -18,11 +18,13 @@
 import org.apache.hc.client5.http.classic.methods.HttpPost;
 import org.apache.hc.client5.http.classic.methods.HttpPut;
 import org.apache.hc.client5.http.classic.methods.HttpUriRequestBase;
+import org.apache.hc.client5.http.config.RequestConfig;
 import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
 import org.apache.hc.core5.http.ClassicHttpResponse;
 import org.apache.hc.core5.http.ContentType;
 import org.apache.hc.core5.http.io.entity.ByteArrayEntity;
 import org.apache.hc.core5.http.io.entity.InputStreamEntity;
+import org.apache.hc.core5.util.Timeout;
 import org.eclipse.rdf4j.http.client.spi.HttpHeader;
 import org.eclipse.rdf4j.http.client.spi.HttpRequest;
 import org.eclipse.rdf4j.http.client.spi.HttpRequestBody;
@@ -101,6 +103,11 @@ private HttpUriRequestBase buildRequest(HttpRequest request) throws IOException
 			hcRequest.addHeader(header.getName(), header.getValue());
 		}
 
+		// Apply per-request response timeout if present
+		request.getResponseTimeout()
+				.ifPresent(timeout -> hcRequest
+						.setConfig(RequestConfig.custom().setResponseTimeout(Timeout.of(timeout)).build()));
+
 		// Set body. Repeatable (byte-backed) bodies use ByteArrayEntity so that Apache HC5's
 		// RedirectExec can follow redirects and the 408 retry loop can re-send the request.
 		// Single-use stream bodies use InputStreamEntity (non-repeatable); RedirectExec will

core/http/client-api/src/main/java/org/eclipse/rdf4j/http/client/spi/HttpRequest.java

@@ -11,6 +11,7 @@
 package org.eclipse.rdf4j.http.client.spi;
 
 import java.net.URI;
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
@@ -48,12 +49,14 @@ public class HttpRequest {
 	private final URI uri;
 	private final List<HttpHeader> headers;
 	private final HttpRequestBody body;
+	private final Duration responseTimeout;
 
 	private HttpRequest(Builder builder) {
 		this.method = builder.method;
 		this.uri = builder.uri;
 		this.headers = new ArrayList<>(builder.headers);
 		this.body = builder.body;
+		this.responseTimeout = builder.responseTimeout;
 	}
 
 	/**
@@ -142,6 +145,17 @@ public Optional<HttpRequestBody> getBody() {
 		return Optional.ofNullable(body);
 	}
 
+	/**
+	 * Returns the optional response timeout for this request. When present, the HTTP client must abort the request if
+	 * no response data arrives within this duration. Overrides any client-level socket timeout for this specific
+	 * request.
+	 *
+	 * @return an {@link Optional} containing the response timeout, or empty if no per-request timeout is set
+	 */
+	public Optional<Duration> getResponseTimeout() {
+		return Optional.ofNullable(responseTimeout);
+	}
+
 	/**
 	 * Creates a new {@link Builder} for the given HTTP method and target URI.
 	 *
@@ -165,7 +179,8 @@ public static Builder newBuilder(String method, URI uri) {
 	public static Builder copyOf(HttpRequest original, URI uri) {
 		return new Builder(original.method, uri)
 				.headers(original.headers)
-				.body(original.body);
+				.body(original.body)
+				.responseTimeout(original.responseTimeout);
 	}
 
 	/**
@@ -181,6 +196,7 @@ public static final class Builder {
 		private final URI uri;
 		private final List<HttpHeader> headers = new ArrayList<>();
 		private HttpRequestBody body;
+		private Duration responseTimeout;
 
 		private Builder(String method, URI uri) {
 			this.method = method;
@@ -236,6 +252,19 @@ public Builder body(HttpRequestBody body) {
 			return this;
 		}
 
+		/**
+		 * Sets the response timeout for this request. When set, the HTTP client must abort the request if no response
+		 * data arrives within this duration, overriding any client-level socket timeout. Pass {@code null} to clear a
+		 * previously set timeout.
+		 *
+		 * @param timeout the response timeout, or {@code null} for no per-request timeout
+		 * @return this builder
+		 */
+		public Builder responseTimeout(Duration timeout) {
+			this.responseTimeout = timeout;
+			return this;
+		}
+
 		/**
 		 * Builds and returns the immutable {@link HttpRequest}.
 		 *

core/http/client-jdk/src/main/java/org/eclipse/rdf4j/http/client/jdk/JdkRDF4JHttpClient.java

@@ -53,8 +53,10 @@ public org.eclipse.rdf4j.http.client.spi.HttpResponse execute(org.eclipse.rdf4j.
 				builder.header(header.getName(), header.getValue());
 			}
 
-			// Set socket timeout if configured
-			if (config.getSocketTimeoutMs() > 0) {
+			// Per-request response timeout takes precedence over the global socket timeout from config
+			if (request.getResponseTimeout().isPresent()) {
+				builder.timeout(request.getResponseTimeout().get());
+			} else if (config.getSocketTimeoutMs() > 0) {
 				builder.timeout(Duration.ofMillis(config.getSocketTimeoutMs()));
 			}
 

core/http/client/src/main/java/org/eclipse/rdf4j/http/client/RDF4JProtocolSession.java

@@ -22,6 +22,7 @@
 import java.net.URI;
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Locale;
@@ -855,6 +856,9 @@ protected HttpRequest getQueryMethod(QueryLanguage ql, String query, String base
 		for (Map.Entry<String, String> additionalHeader : getAdditionalHttpHeaders().entrySet()) {
 			builder.header(additionalHeader.getKey(), additionalHeader.getValue());
 		}
+		if (maxQueryTime > 0) {
+			builder.responseTimeout(Duration.ofSeconds(maxQueryTime));
+		}
 		return builder.build();
 	}
 
@@ -918,6 +922,9 @@ protected HttpRequest getUpdateMethod(QueryLanguage ql, String update, String ba
 		for (Map.Entry<String, String> additionalHeader : getAdditionalHttpHeaders().entrySet()) {
 			builder.header(additionalHeader.getKey(), additionalHeader.getValue());
 		}
+		if (maxExecutionTime > 0) {
+			builder.responseTimeout(Duration.ofSeconds(maxExecutionTime));
+		}
 		return builder.build();
 	}
 

core/http/client/src/main/java/org/eclipse/rdf4j/http/client/SPARQLProtocolSession.java

@@ -22,6 +22,7 @@
 import java.net.HttpURLConnection;
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
@@ -498,6 +499,9 @@ protected HttpRequest getQueryMethod(QueryLanguage ql, String query, String base
 		for (Map.Entry<String, String> additionalHeader : additionalHttpHeaders.entrySet()) {
 			builder.header(additionalHeader.getKey(), additionalHeader.getValue());
 		}
+		if (maxQueryTime > 0) {
+			builder.responseTimeout(Duration.ofSeconds(maxQueryTime));
+		}
 		return builder.build();
 	}
 
@@ -529,6 +533,9 @@ protected HttpRequest getUpdateMethod(QueryLanguage ql, String update, String ba
 				builder.header(additionalHeader.getKey(), additionalHeader.getValue());
 			}
 		}
+		if (maxQueryTime > 0) {
+			builder.responseTimeout(Duration.ofSeconds(maxQueryTime));
+		}
 		return builder.build();
 	}
 

core/http/client/src/main/java/org/eclipse/rdf4j/http/client/query/AbstractHTTPQuery.java

@@ -70,8 +70,10 @@ public Binding[] getBindingsArray() {
 	@Override
 	public void setMaxExecutionTime(int maxExecutionTimeSeconds) {
 		super.setMaxExecutionTime(maxExecutionTimeSeconds);
-		// TODO allow per query timeouts on the http connection used
-		// Note: connection timeout is now configured via HttpClientConfig when building the client.
+		// maxExecutionTimeSeconds is propagated as a per-request response timeout on the HTTP connection:
+		// concrete subclasses pass getMaxExecutionTime() to SPARQLProtocolSession, which sets it on the
+		// HttpRequest via HttpRequest.Builder#responseTimeout(Duration). The ApacheHC5RDF4JHttpClient
+		// implementation applies it as a per-request RequestConfig#setResponseTimeout override.
 	}
 
 	@Override

core/http/client/src/test/java/org/eclipse/rdf4j/http/client/SPARQLProtocolSessionTest.java

@@ -22,12 +22,14 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.nio.charset.StandardCharsets;
+import java.time.Duration;
 import java.util.List;
 import java.util.concurrent.Executors;
 import java.util.stream.Stream;
 
 import org.apache.commons.io.IOUtils;
 import org.eclipse.rdf4j.http.client.spi.HttpHeader;
+import org.eclipse.rdf4j.http.client.spi.HttpRequest;
 import org.eclipse.rdf4j.http.client.spi.HttpResponse;
 import org.eclipse.rdf4j.http.client.spi.RDF4JHttpClient;
 import org.eclipse.rdf4j.http.client.spi.RDF4JHttpClients;
@@ -299,6 +301,32 @@ public void testTupleQuery_Passthrough_ConfiguredFalse(String factoryName, MockS
 		assertThat(out.toString()).startsWith("<");
 	}
 
+	@ParameterizedTest(name = "[{0}]")
+	@MethodSource("httpClientFactories")
+	public void getQueryMethod_setsResponseTimeout_whenMaxQueryTimeIsPositive(String factoryName) {
+		this.factoryName = factoryName;
+		sparqlSession = createProtocolSession();
+
+		HttpRequest request = sparqlSession.getQueryMethod(
+				QueryLanguage.SPARQL, "SELECT * WHERE { ?s ?p ?o }", null, null, true, 30);
+
+		assertThat(request.getResponseTimeout())
+				.isPresent()
+				.hasValue(Duration.ofSeconds(30));
+	}
+
+	@ParameterizedTest(name = "[{0}]")
+	@MethodSource("httpClientFactories")
+	public void getQueryMethod_noResponseTimeout_whenMaxQueryTimeIsZero(String factoryName) {
+		this.factoryName = factoryName;
+		sparqlSession = createProtocolSession();
+
+		HttpRequest request = sparqlSession.getQueryMethod(
+				QueryLanguage.SPARQL, "SELECT * WHERE { ?s ?p ?o }", null, null, true, 0);
+
+		assertThat(request.getResponseTimeout()).isEmpty();
+	}
+
 	@Test
 	public void getContentTypeSerialisationTest() {
 		{