build: add a runnable sdk-example module as an end-to-end smoke test#102
Merged
Conversation
This was referenced Jun 16, 2026
Until now nothing exercised the assembled toolkit as a whole, and there
was no executable reference showing how the pluggable seams fit together.
Add `sdk-example`, an `application`-plugin module that wires the four
pluggable pieces and issues a real HTTP exchange through the public API:
- OkioIoProvider installed into the Io seam,
- the OkHttp transport as the terminal HttpClient,
- an HttpPipeline carrying one step per user-installable pillar
(REDIRECT, RETRY, AUTH, LOGGING),
- JacksonSerde for typed request/response bodies.
The request runs against an embedded mockwebserver3 driven from `main()`,
so the sample is deterministic and needs no network: `:sdk-example:run`
serializes a typed request, POSTs it, and deserializes the typed response.
The AUTH pillar refuses to stamp credentials over plaintext, so the
embedded server speaks HTTPS with a self-signed certificate (okhttp-tls)
and the transport is configured to trust it — the same shape a production
caller would use. A smoke test drives the identical wiring under `build`.
The module is intentionally not a published library, so it opts out of
the gates that only make sense for the public ABI:
- no `maven-publish`/`signing` — it is a sample, never released;
- excluded from binary-compatibility checks via
`apiValidation.ignoredProjects`, since application code has no stable
ABI to snapshot;
- left out of the Kover aggregate (it does not apply the plugin), so
`main()`-centric sample code does not drag the 80% line-coverage floor
down. Its smoke test still runs and proves the sample works.
It keeps explicit-API strict mode, ktlint, detekt, and allWarningsAsErrors
(inherited from the root build) and stays on the Java 8 toolchain.
…olding in example
Depend on the non-junit5 `mockwebserver3` in the sample: it manages the embedded server's lifecycle by hand from main() and the smoke test, so the JUnit 5 extension — and the JUnit it would otherwise drag onto the runtime classpath — is not needed. Also document the retry pillar's idempotency behavior in the sample (the POST is retried because its in-memory body is replayable, so point readers at IdempotencyKeyStep for non-idempotent writes) and update the module count in CLAUDE.md to eleven, noting sdk-example as an unpublished usage sample.
OmarAlJarrah
force-pushed
the
build/example-module
branch
from
0650744 to
987c36a
Compare
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
1 participant
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
Adds an
sdk-exampleapplication module that exercises the assembled SDK end-to-end, as a usability smoke test. It wires all four pluggable seams —OkioIoProvider(I/O),OkHttpTransport(transport), anHttpPipelinewith one step per user-installable pillar, andJacksonSerde— and performs a typed request/response round-trip against an embedded HTTPSMockWebServer(deterministic, no network access required). A JUnit smoke test drives the same wiring underbuild.Gate handling (all satisfied, none weakened):
apiValidation(no stable ABI for an app);Full
./gradlew buildis green with the module included, and./gradlew :sdk-example:runprints the typed round-trip.Closes #73