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).