From 4965887faa2fb5e1bcf895e4f47e7dc417732ccd Mon Sep 17 00:00:00 2001 From: WMK666666 <3496319356@qq.com> Date: Fri, 13 Nov 2026 16:24:31 +0800 Subject: [PATCH] feat(client): send a bearer token in the Authorization header docling-serve can require an API key of its own: with DOCLING_SERVE_API_KEY set, every request must carry it in the X-Api-Key header, which is what the existing apiKey option sends. It can also be put behind a proxy that authenticates the caller on a bearer token, the oauth-proxy deployment in its docs being one such setup. The client only knew the API key, so there was no way to talk to a docling-serve sitting behind that proxy. Add a bearerToken option next to apiKey. It is sent as "Authorization: Bearer " on every request, independently of the API key, and it is masked together with the API key when request logging is enabled. The setter goes on the concrete builders only, not on the deprecated DoclingApiBuilder interface, which is documented as not gaining new configuration options and which third-party implementations must keep compiling. As for every option added since that deprecation, LegacyProviderAdapter reports it as unsupported, so a caller going through a legacy factory gets an error naming the factory instead of the token being silently dropped. The tests live in a @Nested class of AbstractDoclingServeClientTests and build their client through the newClient(DoclingServeApiConfig) hook the shared suite declares, so they run against both the Jackson 2 and the Jackson 3 client, and DoclingServeClientProviderTests covers the DoclingServeApi.builder() path the docs show. The javadoc, the client docs, whats-new and the provider migration guide describe both credentials. Signed-off-by: WMK666666 <3496319356@qq.com> --- .../serve/api/DoclingServeApiBuilder.java | 11 ++++ .../serve/api/DoclingServeApiConfig.java | 25 +++++++- .../serve/api/DoclingServeApiConfigTests.java | 3 + .../serve/api/LegacyProviderAdapterTests.java | 2 +- .../serve/client/DoclingServeClient.java | 23 ++++++- .../client/operations/HttpOperations.java | 6 ++ ...AbstractDoclingServeClientConfigTests.java | 6 +- .../AbstractDoclingServeClientTests.java | 63 +++++++++++++++++++ .../DoclingServeClientProviderTests.java | 19 ++++++ .../DoclingServeJackson2ClientTests.java | 13 ++-- .../DoclingServeJackson3ClientTests.java | 13 ++-- .../serve-api-provider-migration.md | 3 +- .../doc/docs/docling-serve/serve-client.md | 24 +++++++ docs/src/doc/docs/whats-new.md | 1 + 14 files changed, 199 insertions(+), 13 deletions(-) diff --git a/docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeApiBuilder.java b/docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeApiBuilder.java index 4dfe2c2f..11d1c898 100644 --- a/docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeApiBuilder.java +++ b/docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeApiBuilder.java @@ -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. * diff --git a/docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeApiConfig.java b/docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeApiConfig.java index f376148d..6d13e285 100644 --- a/docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeApiConfig.java +++ b/docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeApiConfig.java @@ -44,6 +44,19 @@ public final class DoclingServeApiConfig { */ public static final ConfigOption API_KEY = ConfigOption.of("apiKey", String.class); + /** + * The bearer token used to authenticate requests, sent as {@code Authorization: Bearer }. + * Not set by default. + * + *

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. + * + *

Providers must honor this option when it is set. + */ + public static final ConfigOption BEARER_TOKEN = ConfigOption.of("bearerToken", String.class); + /** * Whether requests are logged. Defaults to {@code false}. * @@ -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> 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); @@ -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. * diff --git a/docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/DoclingServeApiConfigTests.java b/docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/DoclingServeApiConfigTests.java index 84b31672..9aed087e 100644 --- a/docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/DoclingServeApiConfigTests.java +++ b/docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/DoclingServeApiConfigTests.java @@ -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) @@ -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) @@ -179,6 +181,7 @@ private static DoclingServeApiBuilder fullyConfigured() { return DoclingServeApi.builder() .baseUrl("http://example.com:8080") .apiKey("key") + .bearerToken("token") .logRequests() .logResponses() .prettyPrint() diff --git a/docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/LegacyProviderAdapterTests.java b/docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/LegacyProviderAdapterTests.java index 67683a15..4d0f7f32 100644 --- a/docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/LegacyProviderAdapterTests.java +++ b/docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/LegacyProviderAdapterTests.java @@ -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 diff --git a/docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/DoclingServeClient.java b/docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/DoclingServeClient.java index c99b921c..7e54d58c 100644 --- a/docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/DoclingServeClient.java +++ b/docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/DoclingServeClient.java @@ -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); } private Map.Entry> maskSensitiveHeaderValues(Map.Entry> entry) { @@ -330,6 +330,12 @@ protected HttpRequest.Builder createRequestBuilder(RequestContext 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; } @@ -604,6 +610,21 @@ public B apiKey(@Nullable String apiKey) { return (B) this; } + /** + * Sets the bearer token used to authenticate requests. + * + *

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. * diff --git a/docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/operations/HttpOperations.java b/docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/operations/HttpOperations.java index bc9c215a..1e55ff66 100644 --- a/docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/operations/HttpOperations.java +++ b/docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/operations/HttpOperations.java @@ -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 }, 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}. * diff --git a/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/AbstractDoclingServeClientConfigTests.java b/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/AbstractDoclingServeClientConfigTests.java index 5bea1154..5268fb8b 100644 --- a/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/AbstractDoclingServeClientConfigTests.java +++ b/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/AbstractDoclingServeClientConfigTests.java @@ -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; @@ -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) @@ -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 @@ -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) @@ -150,6 +153,7 @@ private DoclingServeClient fullyConfiguredClient() { return newClientBuilder() .baseUrl(getWireMock().baseUrl()) .apiKey("key") + .bearerToken("token") .logRequests() .logResponses() .prettyPrint() diff --git a/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/AbstractDoclingServeClientTests.java b/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/AbstractDoclingServeClientTests.java index da8157a4..d383526c 100644 --- a/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/AbstractDoclingServeClientTests.java +++ b/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/AbstractDoclingServeClientTests.java @@ -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; @@ -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; @@ -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. + * + *

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 @@ -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 diff --git a/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/DoclingServeClientProviderTests.java b/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/DoclingServeClientProviderTests.java index 125a33c5..2954649a 100644 --- a/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/DoclingServeClientProviderTests.java +++ b/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/DoclingServeClientProviderTests.java @@ -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")))); diff --git a/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/DoclingServeJackson2ClientTests.java b/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/DoclingServeJackson2ClientTests.java index 52ae6b10..4cdb6769 100644 --- a/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/DoclingServeJackson2ClientTests.java +++ b/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/DoclingServeJackson2ClientTests.java @@ -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(); } diff --git a/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/DoclingServeJackson3ClientTests.java b/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/DoclingServeJackson3ClientTests.java index abb504b2..6c7e2486 100644 --- a/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/DoclingServeJackson3ClientTests.java +++ b/docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/DoclingServeJackson3ClientTests.java @@ -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(); } diff --git a/docs/src/doc/docs/docling-serve/serve-api-provider-migration.md b/docs/src/doc/docs/docling-serve/serve-api-provider-migration.md index 743728fd..ee04aed0 100644 --- a/docs/src/doc/docs/docling-serve/serve-api-provider-migration.md +++ b/docs/src/doc/docs/docling-serve/serve-api-provider-migration.md @@ -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()) @@ -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. diff --git a/docs/src/doc/docs/docling-serve/serve-client.md b/docs/src/doc/docs/docling-serve/serve-client.md index 232d20a1..6b44ab6e 100644 --- a/docs/src/doc/docs/docling-serve/serve-client.md +++ b/docs/src/doc/docs/docling-serve/serve-client.md @@ -134,6 +134,30 @@ DoclingServeApi api = DoclingServeApi.builder() Note: When using plain `http://`, the client enforces HTTP/1.1 for compatibility with FastAPI, which avoids HTTP/2 downgrade mishaps in some environments. +### Authentication + +docling-serve can require an API key of its own, and it can also be put behind a proxy that +authenticates the caller. Two credentials are supported, and they can be combined if your proxy asks +for one and docling-serve itself for the other: + +```java +// docling-serve's own API key, sent as X-Api-Key, when the server is started with +// DOCLING_SERVE_API_KEY set +DoclingServeApi withApiKey = DoclingServeApi.builder() + .baseUrl("http://localhost:8000") + .apiKey(System.getenv("DOCLING_SERVE_API_KEY")) + .build(); + +// A bearer token, sent as Authorization: Bearer , which is what a proxy in front of +// docling-serve authenticates on, such as its oauth-proxy deployment +DoclingServeApi withBearerToken = DoclingServeApi.builder() + .baseUrl("https://serve.example.com") + .bearerToken(accessToken) + .build(); +``` + +Both values are masked when request logging is enabled. + ### HTTP client customization (timeouts, proxies, TLS) You can supply and tune a `java.net.http.HttpClient.Builder` through the client-specific builder: diff --git a/docs/src/doc/docs/whats-new.md b/docs/src/doc/docs/whats-new.md index eb5356fe..dea3be4e 100644 --- a/docs/src/doc/docs/whats-new.md +++ b/docs/src/doc/docs/whats-new.md @@ -26,6 +26,7 @@ Docling Java {{ gradle.project_version }} includes important breaking changes, a ### {{ gradle.project_version }} +* **New `bearerToken` option** — `DoclingServeApi.builder().bearerToken(token)` sends `Authorization: Bearer ` on every request, for a `docling-serve` behind a proxy that authenticates on bearer tokens, such as the [`oauth-proxy` deployment](https://github.com/docling-project/docling-serve/blob/main/docs/deployment.md#secure-deployment-with-oauth-proxy). It is independent of `apiKey` (sent as `X-Api-Key`), so both can be set. The token is masked when request logging is enabled. Legacy `DoclingServeApiBuilderFactory` implementations don't support it and fail if it is set. * **A failed async task reports the reason given by Docling Serve** — When an async conversion or chunking task failed, the exception only showed the task metadata, which holds document counts, so the cause of the failure was lost. `TaskStatusPollResponse` now has an `errorMessage` field, mapped from the `error_message` that Docling Serve returns, and the exception message includes it when it is present. How much detail that message carries depends on the server's error-sanitization setting: by default Docling Serve reports a generic `Internal processing error.` for most infrastructure failures, and the underlying exception text only when it is started with `DOCLING_SERVE_DEBUG_ERROR_DETAILS=true`. * **New `HeadingHierarchyOptions` and `headingHierarchyOptions` on `ConvertDocumentOptions`** — When set, `headingHierarchyOptions` enables PDF section-header level inference from bookmarks, outline numbering and visual style. The helper getter `doPdfHeadingHierarchy()` is derived from the presence of these options (returns `true` when non-null, `false` otherwise), so callers only need to pass the options to enable hierarchy inference. The options class covers all docling-serve fields (`useBookmarks`, `useNumbering`, `useStyle`, `useFontStyle`, `styleSizeTolerance`, `numberingSchemes`, `maxLevel`, `bookmarkMatchThreshold`). * **Breaking: new `DoclingServeApiProvider` SPI** — Implementations are now provided through `ai.docling.serve.api.spi.DoclingServeApiProvider`, which receives an immutable `DoclingServeApiConfig`, so new options can be added without breaking implementations. A provider can declare the options it doesn't honor via `unsupportedOptions()`, to have them ignored, logged or rejected when a caller sets them. `DoclingServeApi` has a new abstract `config()` method. `DoclingServeApiBuilderFactory`, `DoclingServeApi.DoclingApiBuilder` and `DoclingServeApi.toBuilder()` are deprecated for removal; legacy factories are still used when no provider is found. `docling-serve-api` now depends on `slf4j-api`. See [Migrating to `DoclingServeApiProvider`](docling-serve/serve-api-provider-migration.md).