Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,17 @@ public DoclingServeApiBuilder apiKey(@Nullable String apiKey) {
return set(DoclingServeApiConfig.API_KEY, apiKey);
}

/**
* Sets the bearer token used to authenticate requests.
*
* @param bearerToken the bearer token, or {@code null} to unset it
* @return this builder
* @see DoclingServeApiConfig#BEARER_TOKEN
*/
public DoclingServeApiBuilder bearerToken(@Nullable String bearerToken) {
return set(DoclingServeApiConfig.BEARER_TOKEN, bearerToken);
}

/**
* Enables logging of requests.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,19 @@ public final class DoclingServeApiConfig {
*/
public static final ConfigOption<String> API_KEY = ConfigOption.of("apiKey", String.class);

/**
* The bearer token used to authenticate requests, sent as {@code Authorization: Bearer <token>}.
* Not set by default.
*
* <p>This is what a proxy that authenticates on bearer tokens expects, such as the
* {@code oauth-proxy} deployment in the docling-serve docs. It is independent of {@link #API_KEY},
* which is what docling-serve itself checks against the {@code X-Api-Key} header when
* {@code DOCLING_SERVE_API_KEY} is set.
*
* <p>Providers must honor this option when it is set.
*/
public static final ConfigOption<String> BEARER_TOKEN = ConfigOption.of("bearerToken", String.class);

/**
* Whether requests are logged. Defaults to {@code false}.
*
Expand Down Expand Up @@ -110,7 +123,7 @@ public final class DoclingServeApiConfig {
* adapter, and the tests guarding that every option has an accessor and a setter.
*/
static final List<ConfigOption<?>> ALL_OPTIONS = List.of(
BASE_URL, API_KEY, LOG_REQUESTS, LOG_RESPONSES, PRETTY_PRINT, CONNECT_TIMEOUT, READ_TIMEOUT, ASYNC_POLL_INTERVAL, ASYNC_TIMEOUT, ASYNC_EXECUTOR);
BASE_URL, API_KEY, BEARER_TOKEN, LOG_REQUESTS, LOG_RESPONSES, PRETTY_PRINT, CONNECT_TIMEOUT, READ_TIMEOUT, ASYNC_POLL_INTERVAL, ASYNC_TIMEOUT, ASYNC_EXECUTOR);

private static final URI DEFAULT_BASE_URL = URI.create("http://localhost:5001");
private static final Duration DEFAULT_CONNECT_TIMEOUT = Duration.ofSeconds(5);
Expand Down Expand Up @@ -158,6 +171,16 @@ public URI baseUrl() {
return get(API_KEY);
}

/**
* The bearer token used to authenticate requests.
*
* @return the bearer token, or {@code null} if not set
* @see #BEARER_TOKEN
*/
public @Nullable String bearerToken() {
return get(BEARER_TOKEN);
}

/**
* Whether requests are logged.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ void defaultsWhenNothingIsSet() {
assertThat(config)
.returns(URI.create("http://localhost:5001"), DoclingServeApiConfig::baseUrl)
.returns(null, DoclingServeApiConfig::apiKey)
.returns(null, DoclingServeApiConfig::bearerToken)
.returns(false, DoclingServeApiConfig::logRequests)
.returns(false, DoclingServeApiConfig::logResponses)
.returns(false, DoclingServeApiConfig::prettyPrint)
Expand All @@ -51,6 +52,7 @@ void setOptionsAreReturnedAndRecordedAsExplicitlySet() {
assertThat(config)
.returns(URI.create("http://example.com:8080"), DoclingServeApiConfig::baseUrl)
.returns("key", DoclingServeApiConfig::apiKey)
.returns("token", DoclingServeApiConfig::bearerToken)
.returns(true, DoclingServeApiConfig::logRequests)
.returns(true, DoclingServeApiConfig::logResponses)
.returns(true, DoclingServeApiConfig::prettyPrint)
Expand Down Expand Up @@ -179,6 +181,7 @@ private static DoclingServeApiBuilder fullyConfigured() {
return DoclingServeApi.builder()
.baseUrl("http://example.com:8080")
.apiKey("key")
.bearerToken("token")
.logRequests()
.logResponses()
.prettyPrint()
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ void everyLegacyOptionIsReplayed() {
@Test
void optionsAddedAfterTheDeprecationAreUnsupported() {
assertThat(new LegacyProviderAdapter(new RecordingLegacyFactory()).unsupportedOptions())
.containsExactly(Map.entry(DoclingServeApiConfig.ASYNC_EXECUTOR, Unsupported.FAIL));
.containsOnly(Map.entry(DoclingServeApiConfig.ASYNC_EXECUTOR, Unsupported.FAIL), Map.entry(DoclingServeApiConfig.BEARER_TOKEN, Unsupported.FAIL));
}

@Test
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,7 @@ protected void logRequest(HttpRequest request) {
}

private boolean isSensitiveHeader(String headerName) {
return API_KEY_HEADER_NAME.equalsIgnoreCase(headerName);
return API_KEY_HEADER_NAME.equalsIgnoreCase(headerName) || AUTHORIZATION_HEADER_NAME.equalsIgnoreCase(headerName);
Comment thread
edeandrea marked this conversation as resolved.
Resolved
}

private Map.Entry<String, List<String>> maskSensitiveHeaderValues(Map.Entry<String, List<String>> entry) {
Expand Down Expand Up @@ -330,6 +330,12 @@ protected <I, O> HttpRequest.Builder createRequestBuilder(RequestContext<I, O> r
requestBuilder.header(API_KEY_HEADER_NAME, apiKey);
}

var bearerToken = this.config.bearerToken();

if (Utils.isNotNullOrBlank(bearerToken)) {
requestBuilder.header(AUTHORIZATION_HEADER_NAME, "Bearer " + bearerToken);
}

return requestBuilder;
}

Expand Down Expand Up @@ -604,6 +610,21 @@ public B apiKey(@Nullable String apiKey) {
return (B) this;
}

/**
* Sets the bearer token used to authenticate requests.
*
* <p>Deliberately not part of {@link DoclingApiBuilder}: that interface is deprecated and will not gain
* new configuration options, so a third-party implementation of it keeps compiling.
*
* @param bearerToken the bearer token, or {@code null} to unset it
* @return this builder instance for method chaining
* @see DoclingServeApiConfig#BEARER_TOKEN
*/
public B bearerToken(@Nullable String bearerToken) {
this.settings.bearerToken(bearerToken);
return (B) this;
}

/**
* Sets whether requests are logged.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,12 @@ public abstract class HttpOperations {
*/
public static final String API_KEY_HEADER_NAME = "X-Api-Key";

/**
* The header name used to specify a bearer token in HTTP requests.
* The value is sent as {@code Bearer <token>}, which is what an OAuth proxy in front of docling-serve expects.
*/
public static final String AUTHORIZATION_HEADER_NAME = "Authorization";

/**
* Executes an HTTP GET request using the details specified in the provided {@code RequestContext}.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
import static ai.docling.serve.api.DoclingServeApiConfig.ASYNC_POLL_INTERVAL;
import static ai.docling.serve.api.DoclingServeApiConfig.ASYNC_TIMEOUT;
import static ai.docling.serve.api.DoclingServeApiConfig.BASE_URL;
import static ai.docling.serve.api.DoclingServeApiConfig.BEARER_TOKEN;
import static ai.docling.serve.api.DoclingServeApiConfig.CONNECT_TIMEOUT;
import static ai.docling.serve.api.DoclingServeApiConfig.LOG_REQUESTS;
import static ai.docling.serve.api.DoclingServeApiConfig.LOG_RESPONSES;
Expand Down Expand Up @@ -55,6 +56,7 @@ void configReportsEverySetting() {
assertThat(config)
.returns(URI.create(getWireMock().baseUrl()), DoclingServeApiConfig::baseUrl)
.returns("key", DoclingServeApiConfig::apiKey)
.returns("token", DoclingServeApiConfig::bearerToken)
.returns(true, DoclingServeApiConfig::logRequests)
.returns(true, DoclingServeApiConfig::logResponses)
.returns(true, DoclingServeApiConfig::prettyPrint)
Expand All @@ -65,7 +67,7 @@ void configReportsEverySetting() {
.returns(EXECUTOR, DoclingServeApiConfig::asyncExecutor);

assertThat(config.explicitlySetOptions())
.containsExactly(BASE_URL, API_KEY, LOG_REQUESTS, LOG_RESPONSES, PRETTY_PRINT, CONNECT_TIMEOUT, READ_TIMEOUT, ASYNC_POLL_INTERVAL, ASYNC_TIMEOUT, ASYNC_EXECUTOR);
.containsExactly(BASE_URL, API_KEY, BEARER_TOKEN, LOG_REQUESTS, LOG_RESPONSES, PRETTY_PRINT, CONNECT_TIMEOUT, READ_TIMEOUT, ASYNC_POLL_INTERVAL, ASYNC_TIMEOUT, ASYNC_EXECUTOR);
}

@Test
Expand All @@ -77,6 +79,7 @@ void configOfAnUnconfiguredClientReportsTheDefaults() {
assertThat(config)
.returns(URI.create("http://localhost:5001"), DoclingServeApiConfig::baseUrl)
.returns(null, DoclingServeApiConfig::apiKey)
.returns(null, DoclingServeApiConfig::bearerToken)
.returns(false, DoclingServeApiConfig::logRequests)
.returns(false, DoclingServeApiConfig::logResponses)
.returns(false, DoclingServeApiConfig::prettyPrint)
Expand Down Expand Up @@ -150,6 +153,7 @@ private DoclingServeClient fullyConfiguredClient() {
return newClientBuilder()
.baseUrl(getWireMock().baseUrl())
.apiKey("key")
.bearerToken("token")
.logRequests()
.logResponses()
.prettyPrint()
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@
import ai.docling.core.DoclingDocument.SectionHeaderItem;
import ai.docling.core.DoclingDocument.TableCell;
import ai.docling.serve.api.DoclingServeApi;
import ai.docling.serve.api.DoclingServeApiConfig;
import ai.docling.serve.api.chunk.request.HierarchicalChunkDocumentRequest;
import ai.docling.serve.api.chunk.request.HybridChunkDocumentRequest;
import ai.docling.serve.api.chunk.request.options.HierarchicalChunkerOptions;
Expand Down Expand Up @@ -112,6 +113,7 @@
import ai.docling.serve.api.validation.ValidationError;
import ai.docling.serve.api.validation.ValidationErrorDetail;
import ai.docling.serve.api.validation.ValidationException;
import ai.docling.serve.client.operations.HttpOperations;
import ai.docling.testcontainers.serve.DoclingServeContainer;
import ai.docling.testcontainers.serve.config.DoclingServeContainerConfig;

Expand Down Expand Up @@ -166,6 +168,15 @@ public void testFailed(ExtensionContext context, @Nullable Throwable cause) {

protected abstract DoclingServeApi getDoclingClient(boolean requiresAuth, boolean useWiremock);

/**
* A client of the implementation under test, for the given config.
*
* <p>The shared suite runs against more than one implementation, so tests that need a client of their own take
* it from here. {@link DoclingServeApiConfig#toBuilder()} and {@link DoclingServeApi#builder()} both go through
* the provider, which always builds the implementation it prefers.
*/
protected abstract DoclingServeApi newClient(DoclingServeApiConfig config);

/**
* A client that logs and pretty-prints responses, and whose JSON mapper throws an {@link IllegalStateException}
* with the message {@code boom} when it deserializes an {@link Object}, which is what logging a response does
Expand Down Expand Up @@ -498,6 +509,58 @@ void shouldSuccessfullyCallHealthEndpoint() {
}
}

@Nested
class BearerTokenTests {
@AfterEach
void resetStubs() {
getWiremockServer().resetAll();
}

@Test
void sendsTheBearerTokenInTheAuthorizationHeader() {
stubHealth();

var client = newClient(getDoclingClient(false, true).config().toBuilder().bearerToken("my-token").config());

assertThat(client.health().getStatus()).isEqualTo("ok");

getWiremockServer().verify(getRequestedFor(urlPathEqualTo("/health"))
.withHeader(HttpOperations.AUTHORIZATION_HEADER_NAME, equalTo("Bearer my-token")));
}

@Test
void sendsNoAuthorizationHeaderWhenNoBearerTokenIsSet() {
stubHealth();

var client = newClient(getDoclingClient(false, true).config());

assertThat(client.health().getStatus()).isEqualTo("ok");

getWiremockServer().verify(getRequestedFor(urlPathEqualTo("/health"))
.withoutHeader(HttpOperations.AUTHORIZATION_HEADER_NAME));
}

@Test
void bearerTokenIsIndependentOfTheApiKey() {
stubHealth();

var client = newClient(getDoclingClient(false, true).config().toBuilder()
.apiKey("key")
.bearerToken("my-token")
.config());

assertThat(client.health().getStatus()).isEqualTo("ok");

getWiremockServer().verify(getRequestedFor(urlPathEqualTo("/health"))
.withHeader(HttpOperations.AUTHORIZATION_HEADER_NAME, equalTo("Bearer my-token"))
.withHeader(HttpOperations.API_KEY_HEADER_NAME, equalTo("key")));
}

private void stubHealth() {
getWiremockServer().stubFor(get(urlPathEqualTo("/health")).willReturn(okJson("{\"status\": \"ok\"}")));
}
}

// The clients used by these tests log responses and pretty-print them, which is when a response that is not
// JSON, such as an error page from a gateway in front of docling-serve, used to fail while it was being logged
@Nested
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,25 @@ void baseUrlAndApiKeyAreApplied() {
wireMock.verify(1, getRequestedFor(urlPathEqualTo("/path/health")).withHeader(HttpOperations.API_KEY_HEADER_NAME, equalTo("key")));
}

@Test
void bearerTokenIsApplied() {
wireMock.stubFor(
get(urlPathEqualTo("/path/health"))
.withHeader(HttpOperations.AUTHORIZATION_HEADER_NAME, equalTo("Bearer token"))
.willReturn(okJson("{\"status\": \"ok\"}")));

var client = DoclingServeApi.builder()
.baseUrl(wireMock.baseUrl() + "/path")
.bearerToken("token")
.build();

assertThat(client.health())
.extracting(HealthCheckResponse::getStatus)
.isEqualTo("ok");

wireMock.verify(1, getRequestedFor(urlPathEqualTo("/path/health")).withHeader(HttpOperations.AUTHORIZATION_HEADER_NAME, equalTo("Bearer token")));
}

@Test
void asyncExecutorIsApplied() throws Exception {
wireMock.stubFor(post(urlPathEqualTo("/v1/convert/source/async")).willReturn(okJson(taskStatus("success"))));
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,19 +29,24 @@ class DoclingServeJackson2ClientTests extends AbstractDoclingServeClientTests {
@BeforeAll
static void setUp() {
wireMockServer.start();
doclingClient = newClient(DoclingServeApi.builder()
doclingClient = buildClient(DoclingServeApi.builder()
.logRequests()
.logResponses()
.prettyPrint()
.baseUrl(doclingContainer.getApiUrl())
.config());

authDoclingClient = newClient(doclingClient.config().toBuilder().apiKey("key").config());
wiremockDoclingClient = newClient(doclingClient.config().toBuilder().baseUrl(wireMockServer.baseUrl()).config());
authDoclingClient = buildClient(doclingClient.config().toBuilder().apiKey("key").config());
wiremockDoclingClient = buildClient(doclingClient.config().toBuilder().baseUrl(wireMockServer.baseUrl()).config());
}

@Override
protected DoclingServeApi newClient(DoclingServeApiConfig config) {
return buildClient(config);
}

// Not DoclingServeApiConfig.toBuilder().build(): it goes through the provider, which prefers Jackson 3
private static DoclingServeApi newClient(DoclingServeApiConfig config) {
private static DoclingServeApi buildClient(DoclingServeApiConfig config) {
return DoclingServeJackson2Client.builder().config(config).build();
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,19 +30,24 @@ class DoclingServeJackson3ClientTests extends AbstractDoclingServeClientTests {
@BeforeAll
static void setUp() {
wireMockServer.start();
doclingClient = newClient(DoclingServeApi.builder()
doclingClient = buildClient(DoclingServeApi.builder()
.logRequests()
.logResponses()
.prettyPrint()
.baseUrl(doclingContainer.getApiUrl())
.config());

authDoclingClient = newClient(doclingClient.config().toBuilder().apiKey("key").config());
wiremockDoclingClient = newClient(doclingClient.config().toBuilder().baseUrl(wireMockServer.baseUrl()).config());
authDoclingClient = buildClient(doclingClient.config().toBuilder().apiKey("key").config());
wiremockDoclingClient = buildClient(doclingClient.config().toBuilder().baseUrl(wireMockServer.baseUrl()).config());
}

@Override
protected DoclingServeApi newClient(DoclingServeApiConfig config) {
return buildClient(config);
}

// Not DoclingServeApiConfig.toBuilder().build(): it goes through the provider, which prefers Jackson 3
private static DoclingServeApi newClient(DoclingServeApiConfig config) {
private static DoclingServeApi buildClient(DoclingServeApiConfig config) {
return DoclingServeJackson3Client.builder().config(config).build();
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ public final class MyProvider implements DoclingServeApiProvider {
var builder = MyDoclingServeApi.builder()
.baseUrl(config.baseUrl())
.apiKey(config.apiKey())
.bearerToken(config.bearerToken())
.logRequests(config.logRequests())
.logResponses(config.logResponses())
.prettyPrint(config.prettyPrint())
Expand All @@ -66,7 +67,7 @@ public final class MyProvider implements DoclingServeApiProvider {
}
```

Every accessor returns the effective value: the caller's setting, or the default when the caller didn't set it. The only exceptions are `apiKey()` and `asyncExecutor()`, which return `null` when not set.
Every accessor returns the effective value: the caller's setting, or the default when the caller didn't set it. The only exceptions are `apiKey()`, `bearerToken()` and `asyncExecutor()`, which return `null` when not set.

!!! warning
When `asyncExecutor()` returns `null`, keep your implementation's default behavior. Don't replace it with `ForkJoinPool.commonPool()`: `CompletableFuture` doesn't always use the common pool by default, and `CompletableFuture.delayedExecutor(...)` doesn't guard against a common pool without worker threads, for example on a single-CPU container.
Expand Down
Loading
Loading