Skip to content

Decouple HTTP and OpenAPI execution from workflows - #1844

Open
geomagilles wants to merge 4 commits into
open-workflow-specification:mainfrom
geomagilles:codex/decouple-openapi-execution
Open

geomagilles wants to merge 4 commits into
open-workflow-specification:mainfrom
geomagilles:codex/decouple-openapi-execution

Conversation

@geomagilles

@geomagilles geomagilles commented Nov 17, 2026 •

Copy link
Copy Markdown

Why

Other workflow engines need to reuse HTTP execution and OpenAPI request preparation without constructing SDK workflow contexts or adopting the SDK's JSON model. This PR combines the HTTP and OpenAPI work previously split across #1841 and #1844.

Approach

The initial implementation consists of two independently reviewable commits on top of main (d72716a0), following the review discussion. Follow-up commits incorporate main's namespace migration and correct Jakarta response execution:

  1. cb585321 — Move reusable SDK modules into common. This combines the initial HTTP/OpenAPI extraction with the agreed reorganization and documentation updates. It preserves the previous HTTP/OpenAPI behavior and effective-request metadata, retains current main changes, and was compiled and tested independently before work on the second commit.
  2. 62a34be8 — Share SDK HTTP contracts and converters. This illustrates the injectable-converter alternative to facilitate @fjtirado's review. It is a discussion base that he can adapt or replace, not an approved implementation choice. The subsequent maintainer comment supports the converter direction and taking over the second commit; the specific implementation remains for review. Reverting this commit alone restores the independently usable first commit.

Jakarta response execution follow-up

981f35ea addresses review #5994398282. The SDK buffers Jakarta entities on application.executorService(), using the executor already configured on its default client in main. Standalone transports use an owned cached-thread executor, also configured on their owned default client; new JakartaHttpTransport(client, converter, executor) borrows an application executor and closes neither it nor the client. Existing client/converter constructors retain their signatures and own a buffering executor, so close those transports too.

Response reads no longer use the common fork/join pool. Rejected buffering tasks close unexposed responses and complete delivery exceptionally, preserving the rejection if cleanup fails. SDK exchange failures are translated before scheduling, preserving their original error and task position even when the executor has stopped. Borrowed executors must run tasks or reject by throwing, and allow accepted tasks to finish. Silent discard/forced removal cannot guarantee cleanup. Cached pools can grow under stalled reads, so provider read timeouts remain necessary.

Regression tests first failed on the old common-pool buffering and SDK executor selection. Final Jakarta suites pass all 30 cases, including a local server with one stalled body and an independent ready response, executor ownership, rejection cleanup and stopped-executor error translation. The final full reactor, style and review results are recorded below.

The three common modules live under common/, next to impl/, with their own common Maven parent:

  • openworkflow-common-http: JDK HTTP execution, resolved request contracts and shared response/converter contracts; no production dependencies.
  • openworkflow-common-http-jakarta: Jakarta REST transport, depending only on common HTTP and the Jakarta REST API. Applications select their provider.
  • openworkflow-common-openapi: reusable document model, reader SPI, operation lookup, parameter binding, request preparation and execution; depends only on common HTTP.

The SDK's existing JSON/YAML Jackson reader stays in openworkflow-impl-openapi, including its services, reflection metadata and tests. Consumers of common OpenAPI may provide their own reader or add that existing SDK artifact to use Jackson. The optional SDK reader brings SDK implementation dependencies; the common contract does not. Production dependencies point from impl to common. gRPC is left to its own PR.

The root README now describes three SDK uses: generated Java models, the reference workflow engine, and reusable execution components for other engines.

How it works

HttpRequestInfo<B> is the single concrete request implementation extracted from the SDK request: it owns HTTP fields, builder normalization, URI composition and conditional headers. HttpRequestData is removed. The SDK request specializes it only for AuthProvider; it contains no duplicate HTTP state. The usual SDK constructor and accessor JVM signatures are retained, but the request is now a class rather than a record.

The general response contract and raw serializer are shared in common. SDK JDK/Jakarta response classes are constructor-only subclasses of the same native implementations used by autonomous consumers; no internal response wrappers or HTTP state remain in those SDK classes. WorkflowModel parsing and task enrichment live in explicitly injected SDK converter classes. Consumers may inject a converter for their own JSON type and request it through <T> Optional<T> getBodyAsObject(Class<T> type). The shared contract has no dependency on workflow context, task context or WorkflowModel.

The JDK response retains its native buffered payload instead of constructing a value snapshot on delivery. Jakarta retains a native response with a buffered entity, allowing provider conversion and subsequent access to the original bytes for raw output. Borrowed native access is explicit. Compatibility snapshot data remains available for third-party transports, including its existing three-argument response constructor and defensive-copy/equality guarantees.

Non-2xx statuses remain accessible to autonomous consumers. Request and response headers remain separate, multi-valued headers are preserved, and provider header serialization is respected. JDK effective-request metadata comes from the final native request: POST/303/GET reports GET and the final URI including query. Jakarta explicitly reports absent metadata because its portable API cannot guarantee access to the final connector-managed request. Metadata diagnostic strings redact URI and headers.

Validation

  • Jakarta executor follow-up (981f35ea): 43 modules succeeded; 909 cases, 892 passed, 17 existing skips, zero failures/errors, using mvn -B -fae clean verify with Java 21 on macOS ARM64 and Docker. All 30 Jakarta standalone/SDK cases pass. Repository-wide mvn -B -DskipTests spotless:check checkstyle:check passes. Final structured review reports no accepted/actionable findings. Both original executor-selection regressions were observed failing before the fix; no skips, retry or timeout settings were added.
  • Commit 1: 124 tests passed, 2 existing HTTP tests skipped, no failures/errors, in an isolated worktree before starting commit 2. Tests cover JDK/Jakarta HTTP, standalone OpenAPI, SDK compatibility, SDK Jackson reader discovery and a custom common OpenAPI reader with no engine on its classpath.
  • Commit 2: 161 tests passed, 2 existing HTTP tests skipped, no failures/errors. Additional coverage exercises consumer-defined types, real Jersey injected conversion/raw/reconversion from one entity, SDK native/body/header parity, conversion and buffering failure cleanup, cancellation and close-tracking OpenAPI fallback ownership.
  • Repository-wide mvn -B -DskipTests spotless:check checkstyle:check passes on the final state.
  • Common production dependency trees were inspected: no dependency on impl-core or any other engine artifact. Existing reader services and native-image metadata are packaged in the SDK reader artifact.
  • Full local reactor validation on the final head (62a34be8), Java 21 on macOS ARM64 with Docker: 43 modules succeeded; 901 cases, 884 passed, 17 existing skips, zero failures/errors. Commands: mvn -B -DskipTests spotless:check checkstyle:check and mvn -B -fae clean verify. The Maven-provided macOS ARM64 protoc 3.25.8 executable was placed on PATH for the existing gRPC tests. No exclusions, timeout changes, failure-ignore or retries were added. The 17 skips are existing annotations: 12 shell cases disabled on macOS, two HTTP cases, two wait cases and one scheduler case.
  • Latest upstream CI run is marked action_required; no jobs have executed. DCO passes on 981f35ea. Local validation does not confirm the Ubuntu/Temurin CI result; the manually triggered integration-tests profile was not run.
  • Structured review results, complete command logs and per-class reports are retained locally.

The first state was tested before starting the prototype; revert verification checks that removing commit 2 reproduces commit 1's exact tree.

Prototype trade-offs and limits

The converter implementation remains a proposal for review. The default converter supports bytes; consumers explicitly supply their model conversion policy. Native response implementations use identity, avoiding payload hashing. Provider Error paths terminate delivery, close unexposed responses and retain primary failures when cleanup fails; the SDK delivery boundary also handles failure-translation errors. JDK buffers its original body and copies on explicit byte access. Jakarta must buffer the native entity to retain original raw bytes after provider conversion, and byte access can require another copy. An entity that cannot be buffered is rejected and closed before delivery.

The consumer owns the response and must close it, including around conversion. Conversion/buffering failure closes Jakarta resources and preserves the original error if cleanup also fails. Cancelled deliveries and discarded fallback responses are closed; a selected fallback continues even if cleanup fails. Injected clients remain caller-owned. Cancellation abandons delivery and does not guarantee a network abort; provider timeouts still apply. Metadata is limited to what the transport can observe, and Jakarta is tested with Jersey 4.0.3 only.

Existing OpenAPI subset limits remain: no server-variable expansion, cookie/style/explode serialization, external/nested schema references or security-scheme interpretation. Fallback remains explicit and may replay operations with side effects. This is not streaming support or a full OpenAPI implementation.

Revised prototype compatibility notes

This is an unreleased API migration for the autonomous client: replace HttpRequestData with the common concrete HttpRequestInfo<byte[]> and use the shared response interface. Native headers() may contain provider objects as in the original SDK contract; stringHeaders() supplies provider-formatted text. Snapshot responses retain their existing constructor and defensive-copy guarantees. Header normalization, repeated raw request values, effective metadata, common conditional date preparation, SDK binary body accessors and raw output are regression-tested.

The legacy Jakarta raw status-line heuristic remains private and documented; it is not negotiated protocol metadata and can misidentify lowercase HTTP/1.1 headers. JDK uses its native version. The final HTTP modules also pass Javadoc generation. Record-specific reflection, Record assignments and record patterns require migration. Shared request maps are snapshots; extensions that mutate request maps require review. Native-image execution and JPMS module-path use are not validated. These choices remain discussion material for fjtirado and are not presented as approved architecture.

@geomagilles
geomagilles force-pushed the codex/decouple-openapi-execution branch from 298aa77 to 9bbce98 Compare November 17, 2026 21:16
@geomagilles
geomagilles marked this pull request as ready for review November 17, 2026 21:16
Copilot AI balanced review requested due to automatic review settings November 17, 2026 21:16

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified for the standalone OpenAPI and HTTP extraction.

No open issues 🎉

What changed in this PR

Extracts OpenAPI interpretation, request preparation, and execution so external engines can reuse the SDK without workflow contexts. This builds on #1841’s HTTP extraction, which remains included in the current diff; it prepares, but does not implement, Lemline integration.

Changes:

  • Adds a standalone OpenAPI client and optional Jackson reader, retaining existing model and reader package names.
  • Exposes per-call parameter binding, transport-independent requests, and explicit server fallback.
  • Keeps workflow-specific behavior in adapters, copies HTTP builders per invocation, and adds compatibility and standalone coverage.
File Description
impl/​test/​src/​test/​java/​org/​openworkflow/​sdk/​impl/​test/​OpenAPIAdapterCompatibilityTest.java Tests custom readers, separate credentials, and POST fallback.
impl/​test/​src/​test/​java/​org/​openworkflow/​sdk/​impl/​test/​HttpAdapterCompatibilityTest.java Tests HTTP adapter compatibility from #1841.
impl/​README.md Links standalone HTTP usage documentation.
impl/​pom.xml Registers standalone modules and managed dependencies.
impl/​openapi-jackson/​pom.xml Connects the legacy artifact to the standalone reader.
impl/​openapi-client/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​UnifiedOpenAPIReader.java Relocates the existing reader contract.
impl/​openapi-client/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​UnifiedOpenAPI.java Relocates the shared OpenAPI model.
impl/​openapi-client/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​ParameterDefinition.java Makes parameter metadata public.
impl/​openapi-client/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​OperationDefinition.java Exposes operation metadata to standalone callers.
impl/​openapi-client/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​OpenAPIRequest.java Binds parameters and prepares resolved HTTP requests.
impl/​openapi-client/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​OpenAPIProcessor.java Makes operation lookup publicly accessible.
impl/​openapi-client/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​OpenAPIPathResolver.java Houses the existing URI-template implementation.
impl/​openapi-client/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​OpenAPIClient.java Adds preparation, asynchronous execution, and explicit fallback.
impl/​openapi-client/​README.md Documents usage, compatibility, ownership, and supported subset.
impl/​openapi-client/​pom.xml Defines the Jackson-free OpenAPI artifact.
impl/​openapi-client-jackson/​src/​test/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​jackson/​StandaloneOpenAPITest.java Covers standalone execution, binding, fallback, and packaging.
impl/​openapi-client-jackson/​src/​main/​resources/​META-INF/​services/​tools.jackson.databind.JacksonModule Preserves Jackson module discovery.
impl/​openapi-client-jackson/​src/​main/​resources/​META-INF/​native-image/​org.openworkflow.sdk/​openworkflow-openapi-client-jackson/​reflect-config.json Packages model reflection metadata with the reader.
impl/​openapi-client-jackson/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​jackson/​JacksonUnifiedOpenAPIReader.java Relocates the JSON/YAML reader.
impl/​openapi-client-jackson/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​jackson/​JacksonUnifiedOpenAPIMixInModule.java Relocates Jackson mix-in registration.
impl/​openapi-client-jackson/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​jackson/​JacksonUnifiedOpenAPIMixIn.java Relocates OpenAPI serialization annotations.
impl/​openapi-client-jackson/​pom.xml Defines the optional engine-independent reader artifact.
impl/​http/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​jakarta/​http/​JakartaRequestExecutor.java Delegates workflow requests to #1841’s Jakarta transport.
impl/​http/​pom.xml Adds the standalone Jakarta transport dependency.
impl/​http-client/​src/​test/​java/​org/​openworkflow/​sdk/​http/​JdkHttpTransportTest.java Covers standalone JDK transport behavior.
impl/​http-client/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​http/​URIDecodedBuilder.java Relocates the existing URI builder.
impl/​http-client/​src/​main/​java/​org/​openworkflow/​sdk/​http/​JdkHttpTransport.java Provides #1841’s standalone JDK transport.
impl/​http-client/​src/​main/​java/​org/​openworkflow/​sdk/​http/​HttpTransport.java Defines the shared asynchronous transport contract.
impl/​http-client/​src/​main/​java/​org/​openworkflow/​sdk/​http/​HttpResponseData.java Provides buffered, engine-independent response data.
impl/​http-client/​src/​main/​java/​org/​openworkflow/​sdk/​http/​HttpRequestEncoding.java Extracts existing query and form encoding.
impl/​http-client/​src/​main/​java/​org/​openworkflow/​sdk/​http/​HttpRequestData.java Provides resolved, engine-independent request data.
impl/​http-client/​README.md Documents standalone HTTP usage and lifecycle guarantees.
impl/​http-client/​pom.xml Defines the dependency-free HTTP artifact.
impl/​http-client-jakarta/​src/​test/​java/​org/​openworkflow/​sdk/​http/​jakarta/​JakartaHttpTransportTest.java Covers Jakarta buffering, cancellation, and client ownership.
impl/​http-client-jakarta/​src/​main/​java/​org/​openworkflow/​sdk/​http/​jakarta/​JakartaHttpTransport.java Provides standalone Jakarta execution and native-response access.
impl/​http-client-jakarta/​pom.xml Defines the optional Jakarta transport artifact.
impl/​core/​src/​test/​java/​org/​openworkflow/​sdk/​impl/​http/​HttpErrorTranslationTest.java Checks timeout classification and task-position enrichment.
impl/​core/​src/​test/​java/​org/​openworkflow/​sdk/​impl/​http/​DefaultHttpResponseTest.java Checks legacy response-constructor compatibility.
impl/​core/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​http/​WorkflowHttpRequestInfoBuilderFactory.java Adds template copying without reinitializing authentication.
impl/​core/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​http/​DefaultURITemplateResolver.java Delegates to the extracted URI-template implementation.
impl/​core/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​http/​DefaultHttpResponse.java Adapts buffered responses while retaining legacy access.
impl/​core/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​http/​DefaultHttpRequest.java Delegates workflow HTTP execution to the JDK transport.
impl/​core/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​OpenAPIExecutorBuilder.java Supplies a builder copy for each invocation.
impl/​core/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​OpenAPIExecutor.java Delegates parameter binding and isolates invocation builders.
impl/​core/​pom.xml Adds standalone OpenAPI and HTTP dependencies.

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings November 18, 2026 10:31

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are recorded for the standalone OpenAPI and HTTP extraction.

No open issues 🎉

Review effort: Balanced

@fjtirado

Copy link
Copy Markdown
Collaborator

@geomagilles I think this PR and #1841 should be grouper together.
So please close #1841 and update the description of this one. It does not really make sense to review/merge them separately.

@geomagilles geomagilles changed the title Decouple OpenAPI calls from workflow contexts Decouple HTTP and OpenAPI execution from workflows Nov 18, 2026
@geomagilles

Copy link
Copy Markdown
Author

@fjtirado done

Copilot AI balanced review requested due to automatic review settings November 18, 2026 14:37

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

URI reconstruction drops fixed query parameters from the server URL, causing invalid requests for APIs that require them.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Preserve server URL query parameters when building operation URLs

impl/​openapi-client/​src/​main/​java/​org/​openworkflow/​sdk/​impl/​executors/​openapi/​OpenAPIRequest.java:138

The URI reconstruction drops the server URL's query string. For example, a server URL of https://example.test/v1?api-version=2026-01 and operation path /items produces https://example.test/v1/items, so an API that requires that fixed version parameter receives an invalid request. Neither queryParameters nor the transport restores it. Please preserve the server's raw query when joining the operation path and merge it with the operation's query parameters without decoding existing escapes.

Review effort: Balanced

@fjtirado

fjtirado commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

@geomagilles
Sorry for the delay in the response, I wanted to carefully review and undestood the proposal

I would like to do some general consideration about the PRs that you have recently opened (this one and the gRPC one),

First of all, I think is a good idea to make bits of the current implementation reusable to another implementations, so thanks to bring this up and lets work on that direction.

Now, some general considerations for the twp PRs:

  • The general README should be updated to consider this new case, because currently it describe two SDK purposes: provide JAva POJOS generated from specification schema for implementing the spec (as you were doing so far) and to provide a usable, few dependencies, hightly customizable reference implementation that can be run in standalone SDK or integrated (as Quarkus Flow proves) into a enterprise application service. This PRs establishes a new usage that should be reflected there (it is a philosophical milestone ;))
  • As per previous point, I think stuff that is used by the reference implementation but it is also usable by another implementations should not be under current impl directory but located under a new directory (at the same level than impl) called common, so please move the common stuff to that place. Using that approach, the name of the modules will become common-http, common-openapi, common-grpc, common-http-jakarta.

Now, general condiderations for this PR (the HTML/OpenAPI one)

  • I think current openapi module (the one currently containing the jackson marshallling-unmarshalling) should be leave as it is, there is not real need to create an openapi-client-jackson (for users that want to use openapi-common, if they also, want to use jackson, they will include impl-openapi)
  • In the the case of http modules, to be honest, Im not completely satisfied about how the code that remains in the core module looks like. So I want to make a counter proposal (which description is large, but I think is worth it). The classes that you are added int the common module are pretty similar to the ones currently present under impl.http packages. In particular, WorkflowHttpRequestInfo is very similar (and I would argue more tied to the spec) than HttpRequestData and WorkflowHttpReponse is an interface more or lest equivalent to HttpResponseData (and it is an interface because the response handling is different for different REST client api stack and because I wanted to avoid the performance issue that is clearly there in HttpResponseData regarding cloning, hashing and several object-byte[] transformation). I think one of the results of this PR should be to move a refined version of these classes to http-common (not to keep two hierarchies, one in core and anohter in common). Problem is that right now those classes depends on WorkflowContext, TaskContext and WorkflowModel. WorkflowContext and TaskContext dependency can be removed esasily, but WorkflowModel is diffferent case, since it allow direct transformation from the structure used by the REST api and the model user by the workflow without having to have an intermediate partnet (the byte[]). You dealt with that by adding an exchange method, but Im wondering if it wont be better to leave WorklowHttpResponse as a common inteface (that can implement a method that returns a Workflowmodel) and let the HttpTransport layer return a WorkflowHttpRepsonse intance (so JDKTransport return JDKHttpResponse and JakartaTransport return JakartaHttpRepsonse) WorkflowModel is an easy to implement interface that can be easily bridged by any implementation if needed and will provide means for that implementation to achieve serialization improvements avoiding the byte[] step. Alternative, if WorkflowModel depenendecy is really a blocking issue, add a method Optional getBodyAsObject(Class clazz) to WorkflowHttpResonse interface and let the default implementations use ServiceLoader to load converter interfaces or optionally provide them in the constructor/builder of the implementations.

Since the last comment is pretty tricky stuff, which I propose is that this PR becomes a shared effort, you perform the movement and the readme updates I proposed in the my other comments and once you are done, Ill add a new commit implementing what I discuss in my last comment (just let me know if you prefer WorkflowModel vs WorkflowConverter (one of the two has to be there in common to allow extensibility)

@ricardozanini

Copy link
Copy Markdown
Collaborator

+1 to what @fjtirado stated. A common BOM will be great for other implementations to build on top of the OWS SDK one. We can slowly refactor other parts to be there as well in future releases.

@geomagilles

Copy link
Copy Markdown
Author

Thanks @fjtirado for the detailed review and for offering to work on the HTTP refactor together. I agree with the common/ layout and with keeping the Jackson reader in impl-openapi.

I’ll update this PR in two commits. The first will move the shared HTTP and OpenAPI modules under common/, keep the Jackson reader in impl-openapi, and update the root README to explain how other workflow engines can reuse these components. That commit will be ready to review and merge on its own. I’ll handle gRPC in its own PR.

On your WorkflowModel vs converter question, I’d prefer the injectable converter. Lemline already uses Jackson JsonNode, and a typed body accessor would let us request that type directly while still supporting WorkflowModel in the reference implementation.

I’ll put a small prototype of your converter idea in the second commit so we have something concrete to discuss. I’ll keep the existing tests for raw body access and effective request metadata after redirects. If you’d prefer to take the HTTP refactor from the first commit, we can drop the second one. I’ll ping you when both are ready.

@fjtirado

Copy link
Copy Markdown
Collaborator

@geomagilles Great.
Yes, I also think the converter approach is cleaner
I think Ill take the work from your second commit (when ready) based on converter (with the goal of avoiding the "hierarchy" duplication I mentioned on my prev comment)
For grpc (I have not looked it in detail yet) I think the split will be easier, because the dependencies are more stable (there is only one grpc library out there, the google one, while in Http we have many)

Extract resolved HTTP execution and OpenAPI operation preparation into common/http, common/http-jakarta and common/openapi, with common artifact coordinates, a shared Maven parent and root dependency management. Keep production dependencies directed from impl to common and leave gRPC to its own PR.

Keep the JSON/YAML Jackson reader, services, native-image metadata and tests in the existing openworkflow-impl-openapi artifact. Document reusable execution components as the third SDK usage in the root README and update examples and dependencies. Preserve HTTP/OpenAPI behavior, SDK authentication and error policy, multivalued headers and effective JDK request metadata after redirects; Jakarta explicitly reports unavailable final-request metadata.

Combine the original extraction and agreed reorganization in one independently usable commit on current main. Retain main's dependency updates and AssertJ migrations. Reserve shared request/response contracts and injectable converters for the next, independently revertible prototype commit.

Verify 124 passing targeted JDK/Jakarta HTTP, standalone OpenAPI and SDK compatibility tests with two existing skips. Check production dependency trees, custom engine-free reader usage, SDK reader discovery and packaging, and repository-wide format/style checks before starting the prototype.

Keep Jersey test scope local to consumers after moving dependency management. Restore native body preparation before header snapshots, and propagate provider Errors during Jakarta buffering so delivery cannot remain pending. Cover the latter with a regression observed failing before the fix. Remove engine-specific references from the common README examples.

Signed-off-by: Gilles Barbier <gilles@infinitic.io>
Refine the original SDK HTTP abstractions into common rather than keeping parallel request records and response implementations. Remove HttpRequestData; HttpRequestInfo owns the HTTP state and builder. The SDK request specialization owns only authentication and preserves usual constructor/accessor JVM signatures.

Move general response behavior, raw formatting and native JDK/Jakarta implementations into common. SDK response classes are constructor-only subclasses, with WorkflowModel parsing and task error enrichment in explicit injected SDK converters. Preserve effective JDK request metadata, explicit Jakarta absence, multivalued headers, original raw bytes and caller-owned response cleanup.

This remains the converter alternative for discussion with fjtirado, not an approved final design. The SDK request is now a class, so record patterns and record-specific reflection require migration. Standalone callers migrate to the common request class and response interface; stringHeaders provides portable text for native header values.

Jakarta retains a buffered native response until close and rejects unbufferable entities. Byte access and serialized request snapshots still copy. JDK avoids response snapshot cloning and payload hashing. Retain the existing private Jakarta raw-format heuristic as a documented compatibility limit. The preceding extraction/reorganization commit on main remains unchanged and independently usable.

Verify 161 passing targeted HTTP/OpenAPI/SDK compatibility tests with two existing skips, repository-wide style checks, HTTP Javadocs and clean structured review.

Retain current main dependency updates and migrate prototype tests to AssertJ. Propagate provider Errors as well as runtime failures through Jakarta delivery, buffering and conversion while closing owned responses and preserving primary failures.

Cover SDK delivery and OpenAPI status-inspection/cleanup Error paths with regressions observed failing before their fixes, preserving normal workflow error translation and explicit fallback policy.

Keep cause-less CompletionException instances as translation inputs and terminate SDK delivery even if failure translation itself throws. Verify exception identity, task position, closure and bounded completion on these paths.

Signed-off-by: Gilles Barbier <gilles@infinitic.io>
@geomagilles
geomagilles force-pushed the codex/decouple-openapi-execution branch from d40e0c2 to 62a34be Compare November 19, 2026 21:36
Copilot AI balanced review requested due to automatic review settings November 19, 2026 21:36

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the extraction of reusable HTTP and OpenAPI components.

No open issues 🎉

Review effort: Balanced

@geomagilles

Copy link
Copy Markdown
Author

Thanks @fjtirado! The PR now contains exactly two commits on top of main:

  • cb585321: the agreed common/ reorganization and documentation updates, keeping the Jackson reader in impl-openapi. This commit is independently usable.
  • 62a34be8: an implementation of the injectable-converter approach for you to review, adapt or replace. It shares the HTTP request/response implementations rather than maintaining parallel implementations. Reverting it restores the first commit exactly.

Local full-reactor validation passed: 43 modules, 884 tests passed, 17 existing skips, no failures. Spotless and Checkstyle also passed.

The GitHub workflow is awaiting maintainer approval. Could you approve it so we can confirm the Ubuntu CI result?

@fjtirado

Copy link
Copy Markdown
Collaborator

@geomagilles
Thanks for the refactor. This is aligned with what I have in mind.
Before adding my commit (between other things, Im going to add the Workflow prefix to http classes, so they do not collide with other general http frameworks when using IDEs), I have some preliminary question though:

  • In HttpResponse interface we have four retrieval methods, two that return byte[], two that return the converted object, when I foresee just two, one that return the body response as byte[] and another one that use the converter to convert it to the workkflow engine implementation domain object (WorkflowModel in the case of the reference implementaiton). I believe two methods need to be removed from that interface.
  • Why so much cloning on the response? I do not see a real need to clone, neither the headers( that are inmutable so there is no point on cloning), neither. and. specially the body (also, in the case of the response body, cloning it will be a performance killer). Im probably missing some detail, so asking before removing.

@geomagilles

Copy link
Copy Markdown
Author

Thanks @fjtirado, agreed on both points. The Workflow prefix makes sense too.

The extra accessors were compatibility bridges for the existing SDK API. Let’s keep one byte[] body accessor and getBodyAsObject(Class) in common, with legacy aliases and full raw HTTP formatting kept outside that contract.

The cloning came from the immutable HttpResponseData snapshot guarantees. I agree with removing per-read body clones from native responses and reusing headers where they are already immutable. Returned byte arrays should then be documented as borrowed and read-only.

For Jakarta, the buffering preserves the original bytes when raw access follows typed conversion—that’s separate from the extra clones.

Happy for you to simplify this in your commit.

@fjtirado

Copy link
Copy Markdown
Collaborator

@geomagilles
Perfect, Ill let you know when I done (might take a while, I mean Im not sure Ill be able to do it today or in Monday), but I want to have this merged ASAP

@fjtirado

fjtirado commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

@geomagilles
There are always surprises... we had to change the package name prefix becuase administrate domain issues. #1857
Can you update your PRs with the change from org to cloud? Sorry about the incovenience.
Once you are done, Ill resume the work here.

Merge the upstream package rename into the HTTP and OpenAPI changes. Align the common modules, workflow adapters, tests, Maven coordinates, and README examples with the new SDK domain.
Copilot AI balanced review requested due to automatic review settings November 20, 2026 14:35
@geomagilles

Copy link
Copy Markdown
Author

@fjtirado done

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Blocking response buffering on the shared common pool can let stalled bodies prevent unrelated responses from being delivered or closed, requiring a blocking-read executor with defined ownership.

1 open issue

Review effort: Balanced

Reuse application.executorService() for SDK response buffering, matching
main's default Jakarta client configuration. Give standalone transports an
owned cached-thread executor and support explicit borrowing of a caller's
executor. Preserve existing constructors and close only owned resources.

Close unexposed responses when buffering submission is rejected, retaining
the primary scheduling failure when cleanup also fails. Translate SDK
network failures before scheduling so a stopped executor cannot mask the
original cause, timeout classification or task position. Document the
borrowed executor's run-or-throw and graceful task-completion requirements.

Update common HTTP lifecycle documentation and add regressions for executor
selection, a stalled local response alongside a ready response, ownership,
shutdown rejection, cleanup failure and SDK error translation. Observe the
old common-pool and SDK executor assertions fail before applying the fix.

Verify 30 Jakarta standalone/SDK cases and the full clean reactor:
43 modules, 892 passed tests, 17 existing skips, zero failures/errors. Repository-wide Spotless and Checkstyle pass; structured
review is clean. Preserve the existing buffered/raw/converter behavior.

Signed-off-by: Gilles Barbier <gilles@infinitic.io>
Copilot AI balanced review requested due to automatic review settings November 20, 2026 15:03

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Changes to public request/response contracts and module boundaries require maintainer architectural review, while native-image and JPMS compatibility remain unvalidated.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants