feat(api): add PreSignedUrlConvertResponse for PresignedUrlTarget#537
Closed
dan-m62 wants to merge 1 commit into
Closed
feat(api): add PreSignedUrlConvertResponse for PresignedUrlTarget#537dan-m62 wants to merge 1 commit into
dan-m62 wants to merge 1 commit into
Conversation
docling-serve has two distinct response classes for presigned-URL flows
(responses.py:236-243):
- PresignedUrlConvertDocumentResponse: counts-only response returned
when the request targets S3Target or PutTarget, where the document
content is delivered out-of-band to the client-supplied target.
- PresignedUrlConvertResponse: counts plus a per-source documents list
returned when the request targets PresignedUrlTarget, where the
server uploads each artifact to its own object storage and returns
presigned GET URLs in-band.
The existing PreSignedUrlConvertDocumentResponse covers the first case.
This commit adds the second as a sibling class under the existing
sealed ConvertDocumentResponse hierarchy, plus the supporting types
referenced by it:
- PreSignedUrlConvertResponse: final, mirrors all counts plus a
documents field, returns ResponseType.PRE_SIGNED_URL_RESPONSE.
- DocumentArtifactItem: per-source entry on the response.
- ArtifactRef: a single presigned URL plus its artifact_type,
mime_type, and url_expires_at.
- ArtifactType: enum discriminating which output format the artifact
represents (JSON, HTML, MARKDOWN, TEXT, DOCTAGS, RESOURCE_BUNDLE).
- ConversionStatus: enum for the terminal per-document outcome
(PENDING, STARTED, SUCCESS, PARTIAL_SUCCESS, FAILURE, SKIPPED).
- ProfilingItem: per-stage timing record, populated when
DOCLING_DEBUG_PROFILE_PIPELINE_TIMINGS=true on the worker.
- ProfilingScope: enum for ProfilingItem.scope (PAGE, DOCUMENT).
ConvertDocumentResponse permits clause and @JsonSubTypes are updated to
include the new subtype. Jackson's DEDUCTION dispatch routes responses
carrying a documents field to PreSignedUrlConvertResponse and
counts-only responses to PreSignedUrlConvertDocumentResponse.
The existing PreSignedUrlConvertDocumentResponse, its tests, and the
ResponseType.PRE_SIGNED_URL value are unchanged. ResponseType gains a
new PRE_SIGNED_URL_RESPONSE entry for the new sibling, and its class-
level javadoc is updated to correct the previous description of
PRE_SIGNED_URL ("packaged as a ZIP archive and uploaded to the given
target URI") which inverted the relationship.
Tests follow the established target-test pattern: builder construction
plus AssertJ getter assertions for the new types and a both-null and
all-fields pair on ConvertDocumentResponseTests for the new sibling.
Signed-off-by: Daniel Imber <dimber@m62.ai>
Contributor
|
Hi @dan-m62 thank you for this work! I have similar comments here about the tests as I did in #535. The tests here really don't provide any indication that the json marshalling is correct and that it serializes/deserializes properly. t would be better if there were some functional tests in AbstractDoclingServeClientTests that verified that the docling-serve instance actually did things the way it was supposed to based on the input. |
Contributor
|
This is the other half of #541 |
6 tasks
Contributor
edeandrea
added a commit
to edeandrea/docling-java
that referenced
this pull request
Jun 15, 2026
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
- `PreSignedUrlConvertDocumentResponse` gains `numPartiallySucceeded`
field to align with the current OpenAPI spec
- `ConvertOperations` treats `PresignedUrlTarget` as a remote target
- `ConvertDocumentResponse` uses `defaultImpl` for Jackson DEDUCTION
to resolve ambiguity with `PreSignedUrlConvertDocumentResponse`
- 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
added a commit
to edeandrea/docling-java
that referenced
this pull request
Jun 15, 2026
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
added a commit
to edeandrea/docling-java
that referenced
this pull request
Jun 15, 2026
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
added a commit
that referenced
this pull request
Jun 15, 2026
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 #535 and #537.
Closes #541
Assisted-By: Claude Code <noreply@anthropic.com>
Signed-off-by: Eric Deandrea <eric.deandrea@ibm.com>
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
2 participants
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.
Companion to #535, completing the request/response round-trip for the
PresignedUrlTargetflow introduced indocling-servev1.22.0+. When a client submits{"target": {"kind": "presigned_url"}}, theserver's response shape (
PresignedUrlConvertResponseon the Python side) carries:num_converted/num_succeeded/num_partially_succeeded/num_failed/processing_time)documents[]array with per-source artifact metadata:source_index,source_uri,filename,status,errors,timings, andartifacts[](per output format:artifact_type,mime_type,uri,url_expires_at)This is structurally distinct from the existing
PreSignedUrlConvertDocumentResponse(added by #388), which carries only the aggregate counts and is what the server returns fors3/puttargets. The Pythonequivalents are similarly two distinct classes —
PresignedUrlConvertDocumentResponse(counts only) andPresignedUrlConvertResponse(counts + documents). The existing Java class is unchanged.This commit adds:
PreSignedUrlConvertResponse.java: new sibling under the sealedConvertDocumentResponsehierarchy, fingerprinted by the presence ofdocuments(JacksonJsonTypeInfo.Id.DEDUCTION, consistent with therest of this hierarchy — the wire response carries no
kinddiscriminator)DocumentArtifactItem.java,ArtifactRef.java,ArtifactType.java,ConversionStatus.java,ProfilingItem.java,ProfilingScope.java: supporting types, fields verified 1:1 againstdocling-slim2.99.0ResponseType.java: extend withPRE_SIGNED_URL_RESPONSEConvertDocumentResponse.java: extendpermitsand@JsonSubTypesArtifactRefTests,DocumentArtifactItemTests, and two new methods onConvertDocumentResponseTestscovering builder + null-collection + immutability assertions, matching the test scope of the otherresponse tests in this module