Repository navigation
feat(client): send a bearer token in the Authorization header - #785
Conversation
|
@all-contributors add @WMK666666 for code, tests |
edeandrea
left a comment
There was a problem hiding this comment.
Thanks for this, the feature itself looks good and the masking/legacy-adapter handling is nicely thought through. Details are inline, plus a few things on files the PR doesn't touch:
-
Commit message / PR description: docling-serve does have built-in auth: when
DOCLING_SERVE_API_KEYis set, every request must carry it in theX-Api-Keyheader (seeconfiguration.mdandAPIKeyAuthinapp.py). That's what our existingapiKeyoption is for. Theoauth-proxydeployment part is right, but it's one deployment example, not the "normal" deployment. Please reword the commit message accordingly. -
Provider path: please add a bearer token case to
DoclingServeClientProviderTests(alongsidebaseUrlAndApiKeyAreApplied), so theDoclingServeApi.builder()path, which is the one the docs show, is covered. -
What's new: please add an entry under Docling Serve →
{{ gradle.project_version }}indocs/src/doc/docs/whats-new.md, something like:- New
bearerTokenoption —DoclingServeApi.builder().bearerToken(token)sendsAuthorization: Bearer <token>on every request, for adocling-servebehind a proxy that authenticates on bearer tokens, such as theoauth-proxydeployment. It is independent ofapiKey(sent asX-Api-Key), so both can be set. The token is masked when request logging is enabled. LegacyDoclingServeApiBuilderFactoryimplementations don't support it and fail if it is set.
- New
|
I've put up a pull request to add @WMK666666! 🎉 |
:java_duke: JaCoCo coverage report
|
|
||||||||||||||
cecd2ed to
01169cb
Compare
|
Thanks for the detailed review — everything is addressed in Wording. You're right, I had it backwards. Provider path. Added Flaky assertion. Test location. What's new. Added under Docling Serve → Masking. Understood — leaving that gap alone. On verification: |
|
Thanks @WMK666666, nice work on the rework, and good catch on the shared suite! You were right: While verifying that, it turned out the existing suite had the same problem: After the rebase, a few things:
Everything else from the previous round looks good. Thanks again! |
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 <token>" 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>
01169cb to
4965887
Compare
|
Rebased onto
protected abstract DoclingServeApi newClient(DoclingServeApiConfig config);implemented by both subclasses, and var client = newClient(getDoclingClient(false, true).config().toBuilder().bearerToken("my-token").config());One detail worth pointing out: the static helper in each subclass had to be renamed. @Override
protected DoclingServeApi newClient(DoclingServeApiConfig config) {
return buildClient(config);
}Migration guide ( Nit: both On the red CI on the previous head: those two All 24 other jobs in that run were green, including Locally on this head: |
edeandrea
left a comment
There was a problem hiding this comment.
Thank you very much @WMK666666 for this and for working through several rounds of review!
Once CI passes I will merge.
|
HTML test reports are available as workflow artifacts (zipped HTML). • Download: Artifacts for this run |
|
@all-contributors add @WMK666666 for code, test |
|
This project's configuration file has malformed JSON: .all-contributorsrc. Error:: Expected ',' or ']' after array element in JSON at position 7198 (line 277 column 7) |
docling-serve can require an API key of its own: with
DOCLING_SERVE_API_KEYset, every request mustcarry it in the
X-Api-Keyheader, which is what the existingapiKeyoption sends. It can also be putbehind a proxy that authenticates the caller on a bearer token — the
oauth-proxydeployment in its docsis one such setup.
DoclingServeClientonly knew the API key, so there was no way to talk to a docling-serve sitting behindthat proxy.
Change
DoclingServeApiConfig.BEARER_TOKEN(bearerToken,String), with an accessor on the config and asetter on
DoclingServeApiBuilder.DoclingServeClient.createRequestBuildersends it asAuthorization: Bearer <token>on every request,independently of
apiKey. Both may be set at once, for a proxy that asks for one and docling-serveitself for the other.
Authorizationvalue is masked by the same code that masksX-Api-Keywhen request logging is on.DoclingApiBuilderinterface, which is documented as notgaining new configuration options, so third-party implementations of it keep compiling.
LegacyProviderAdaptertherefore reportsbearerTokenasUnsupported.FAIL: a caller going through alegacy factory gets an error naming the factory, instead of the token being silently dropped.
Tests
AbstractDoclingServeClientTests#BearerTokenTests(new@Nestedclass, WireMock): the header is sent,it is not sent when no token is configured, and it is independent of the API key. Being part of the
shared suite, it runs against both the Jackson 2 and the Jackson 3 clients.
protected abstract DoclingServeApi newClient(DoclingServeApiConfig config), implemented by bothsubclasses.
DoclingServeApiConfig.toBuilder()andDoclingServeApi.builder()both go through theprovider, which always builds the implementation it prefers, so they cannot be used for this.
DoclingServeClientProviderTests#bearerTokenIsApplied: theDoclingServeApi.builder()path, which isthe one the docs show, applies the token.
DoclingServeApiConfigTestsandAbstractDoclingServeClientConfigTests: the new option is reported bythe config and appears in
explicitlySetOptions(), which keeps the guards that every option has anaccessor and a setter passing.
LegacyProviderAdapterTests:bearerTokenis listed as unsupported for legacy factories. Theassertion uses
containsOnly, because the expected map comes fromCollectors.toUnmodifiableMapandhas no iteration order.
:docling-serve-api:testand the non-containerdocling-serve-clienttests pass locally. The two*ClientTestsclasses start a docling-serve container and need Docker, which this machine doesn't have.Docs
docs/src/doc/docs/docling-serve/serve-client.md: theAuthenticationsection now says thatdocling-serve can require an API key of its own and can also sit behind a proxy that authenticates on a
bearer token.
docs/src/doc/docs/docling-serve/serve-api-provider-migration.md: the provider example mapsbearerToken, andbearerToken()joinsapiKey()andasyncExecutor()as the accessors that returnnullwhen not set.docs/src/doc/docs/whats-new.md: an entry under Docling Serve →{{ gradle.project_version }}.