feat(api): add PresignedUrlTarget and PreSignedUrlConvertResponse#543
Merged
edeandrea merged 1 commit intoJun 15, 2026
Merged
Conversation
This was referenced Jun 15, 2026
edeandrea
force-pushed
the
feat/presigned-url-target-response
branch
from
d3a8af1 to
adb917f
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
This PR extends the docling-serve-api / docling-serve-client surface to support docling-serve’s server-managed presigned-URL delivery mode (v1.22.0+), adding the request target (PresignedUrlTarget), the corresponding response shape (PreSignedUrlConvertResponse with per-document artifacts), plus supporting model types and Jackson Instant codecs. It also updates client routing, bumps the default Testcontainers image, and expands docs/tests to cover the new round-trip behavior.
Changes:
- Add
PresignedUrlTargetandPreSignedUrlConvertResponse(+ supporting response model types) and wire them into polymorphic (DEDuction-based) response handling. - Add Jackson 2 & 3
Instantserializers/deserializers and use them for presigned artifact expiry timestamps and profiling timestamps. - Update client conversion routing, integration tests (WireMock), and documentation; bump the default docling-serve container image to
v1.24.0.
Reviewed changes
Copilot reviewed 28 out of 28 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Documents the new PRE_SIGNED_URL_RESPONSE response type in the usage snippet. |
| docs/src/doc/docs/whats-new.md | Adds release notes entries for the presigned URL target/response and supporting types (but currently has a duplicated version heading). |
| docs/src/doc/docs/getting-started.md | Updates example switch to include PRE_SIGNED_URL_RESPONSE. |
| docs/src/doc/docs/docling-serve/serve-client.md | Adds target snippet and an end-to-end example for handling PreSignedUrlConvertResponse. |
| docs/src/doc/docs/docling-serve/serve-api.md | Documents the new target, response type, and adds a presigned URL example. |
| docling-testcontainers/src/main/java/ai/docling/testcontainers/serve/config/DoclingServeContainerConfig.java | Bumps default docling-serve image version to v1.24.0. |
| docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/AbstractDoclingServeClientTests.java | Adds WireMock functional tests for PresignedUrlTarget request serialization + PreSignedUrlConvertResponse deserialization (single and multiple documents). |
| docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/operations/ConvertOperations.java | Treats PresignedUrlTarget as a “remote target” so multi-source requests return JSON rather than ZIP streaming. |
| docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/convert/response/DocumentArtifactItemTests.java | Adds unit tests for the new DocumentArtifactItem model. |
| docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/convert/response/ConvertDocumentResponseTests.java | Adds unit tests for the new PreSignedUrlConvertResponse subtype behavior and defaults. |
| docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/convert/response/ArtifactRefTests.java | Adds unit tests for ArtifactRef (including nullable expiry). |
| docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/convert/request/target/PresignedUrlTargetTests.java | Adds a basic round-trip test for PresignedUrlTarget. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/serialization/Jackson3InstantSerializer.java | Adds Jackson 3 Instant serializer used by new response models. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/serialization/Jackson3InstantDeserializer.java | Adds Jackson 3 Instant deserializer used by new response models. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/serialization/Jackson2InstantSerializer.java | Adds Jackson 2 Instant serializer used by new response models. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/serialization/Jackson2InstantDeserializer.java | Adds Jackson 2 Instant deserializer used by new response models. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/ResponseType.java | Adds PRE_SIGNED_URL_RESPONSE enum constant and updates Javadoc for presigned-related response types. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/ProfilingScope.java | Adds profiling scope enum used by new profiling model. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/ProfilingItem.java | Adds profiling item model, including Instant list timestamp handling. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/PreSignedUrlConvertResponse.java | Adds the new per-document presigned URL response subtype. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/PreSignedUrlConvertDocumentResponse.java | Adds numPartiallySucceeded to align with OpenAPI spec. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/DocumentArtifactItem.java | Adds per-source conversion outcome + artifacts container. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/ConvertDocumentResponse.java | Adds PreSignedUrlConvertResponse subtype and sets defaultImpl for DEDUCTION deserialization. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/ConversionStatus.java | Adds conversion status enum for per-document outcomes. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/ArtifactType.java | Adds artifact type enum for presigned artifacts. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/ArtifactRef.java | Adds artifact reference model including presigned URL expiry timestamp. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/request/target/Target.java | Permits and registers PresignedUrlTarget subtype and kind discriminator. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/request/target/PresignedUrlTarget.java | Adds the new marker target type for server-managed presigned URL delivery. |
:java_duke: JaCoCo coverage report
|
|
||||||||||||||
|
HTML test reports are available as workflow artifacts (zipped HTML). • Download: Artifacts for this run |
|
HTML test reports are available as workflow artifacts (zipped HTML). • Download: Artifacts for this run |
edeandrea
force-pushed
the
feat/presigned-url-target-response
branch
from
5dc3472 to
587b4e9
Compare
Add support for the presigned-URL delivery mode introduced in
docling-serve v1.22.0. Clients can now request
`{"target": {"kind": "presigned_url"}}` and receive per-document
artifact download URLs in a `PreSignedUrlConvertResponse`.
New request target:
- `PresignedUrlTarget` — marker class in the `Target` sealed hierarchy
New response types:
- `PreSignedUrlConvertResponse` — extends `ConvertDocumentResponse`
with a `documents` list and aggregate conversion stats
- `DocumentArtifactItem` — per-document result with status and artifacts
- `ArtifactRef` — presigned download URL with expiry timestamp
- Supporting enums: `ArtifactType`, `ConversionStatus`,
`ProfilingScope`
- Supporting type: `ProfilingItem` for per-stage timing data
Additional changes:
- Custom `Instant` serializers/deserializers for Jackson 2 and 3,
following the existing `Duration` serializer pattern
- Custom `ConvertDocumentResponse` deserializers for Jackson 2 and 3
that dispatch based on distinguishing JSON fields and fail fast on
unknown shapes (replaces `@JsonTypeInfo(DEDUCTION)`)
- `PreSignedUrlConvertDocumentResponse` gains `numPartiallySucceeded`
field to align with the current OpenAPI spec
- `ConvertOperations` treats `PresignedUrlTarget` as a remote target
- Default Testcontainers image upgraded from v1.19.0 to v1.24.0
- WireMock functional tests verify full request/response round-trip
- Documentation updated across all relevant files
This work builds on the foundation laid by @dan-m62 in docling-project#535 and docling-project#537.
Closes docling-project#541
Assisted-By: Claude Code <noreply@anthropic.com>
Signed-off-by: Eric Deandrea <eric.deandrea@ibm.com>
edeandrea
force-pushed
the
feat/presigned-url-target-response
branch
from
587b4e9 to
27bc818
Compare
|
HTML test reports are available as workflow artifacts (zipped HTML). • Download: Artifacts for this run |
|
HTML test reports are available as workflow artifacts (zipped HTML). • Download: Artifacts for this run |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PresignedUrlTargetrequest target andPreSignedUrlConvertResponseresponse type for the presigned-URL delivery mode introduced in docling-serve v1.22.0DocumentArtifactItem,ArtifactRef,ArtifactType,ConversionStatus,ProfilingItem,ProfilingScopeInstantserializers/deserializers for Jackson 2 and 3 (following the existingDurationserializer pattern)numPartiallySucceededfield toPreSignedUrlConvertDocumentResponseto align with current OpenAPI specConvertOperationsto treatPresignedUrlTargetas a remote target@JsonTypeInfo(DEDUCTION)+@JsonSubTypesonConvertDocumentResponsewith explicit custom deserializers (Jackson2ConvertDocumentResponseDeserializer/Jackson3ConvertDocumentResponseDeserializer) that dispatch based on distinguishing JSON fields and fail fast on unknown shapesserve-api.md,serve-client.md,getting-started.md,README.md, andwhats-new.mdAcknowledgments
This PR builds on the foundation laid by @dan-m62 in #535 and #537. Their work on
PresignedUrlTarget,PreSignedUrlConvertResponse, and the supporting model types (DocumentArtifactItem,ArtifactRef,ArtifactType,ConversionStatus,ProfilingItem,ProfilingScope) provided the starting point for this implementation. This PR addresses the review feedback on those PRs (functional WireMock tests, polymorphic deserialization,Instanthandling, client routing, docs) and consolidates the changes into a single PR.Supersedes #535 and #537.
Closes #541
Test plan
./gradlew --no-daemon buildpasses (all modules)./gradlew --no-daemon spotlessCheckpassesPresignedUrlTargetTests,ArtifactRefTests,DocumentArtifactItemTests,ConvertDocumentResponseTests)PresignedUrlTargetrequest serialization andPreSignedUrlConvertResponsedeserialization (single and multiple documents)