[AIT-84] feat: add support for returning serials on publish

[ttypic]

• Introduced publishWithResult API to include message serials in the response.
• Added callback-based publishAsync method for asynchronous publishing with serials.
• Deprecated older CompletionListener-based publish methods in favor of Callback<PublishResult>.

Summary by CodeRabbit

• New Features

  • Publish APIs now return a PublishResult with message metadata/serials; async variants expose typed result callbacks.

• Deprecations

  • CompletionListener-based publish overloads marked deprecated; prefer Callback variants.

• Improvements

  • Stronger type-safety for async callbacks across publish and push flows.
  • Non-blocking annotations added to async publish paths.

• Tests

  • Tests updated to use PublishResult serials and async result-based workflows.

• Chores

  • CI Java toolchain and test retry settings adjusted.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

Adds a typed PublishResult flow and Callback-based publish APIs for REST and Realtime channels, makes CompletionListener.ToCallback generic, updates internal publish implementations to return PublishResult-aware requests, and refactors tests to use publish-returned serials.

Changes

Cohort / File(s)	Change Summary
Generic callback infra lib/src/main/java/io/ably/lib/realtime/CompletionListener.java, android/src/main/java/io/ably/lib/push/PushChannel.java, lib/src/main/java/io/ably/lib/push/PushBase.java	Made ToCallback generic (ToCallback<T>) and updated call sites to ToCallback<>(listener); adjusted onSuccess to accept T.
Realtime channel API lib/src/main/java/io/ably/lib/realtime/ChannelBase.java	Added publish overloads accepting Callback<PublishResult> (single and array variants); added internal error-bridge helper; deprecated CompletionListener publish overloads; void overloads delegate to callback variants.
REST channel API lib/src/main/java/io/ably/lib/rest/ChannelBase.java	Added synchronous publishWithResult(...) returning PublishResult; added publishAsync(..., Callback<PublishResult>); changed publishImpl signatures to return Http.Request<PublishResult> and wired response handlers to construct PublishResult.
Realtime tests lib/src/test/java/io/ably/lib/test/realtime/RealtimeChannelMessageEditTest.java, lib/src/test/java/io/ably/lib/test/realtime/RealtimeChannelTest.java	Refactored publishes to use PublishResult or new overloads; removed explicit null CompletionListener args; tests now use publishResult.serials[0] as canonical serial.
REST tests lib/src/test/java/io/ably/lib/test/rest/RestChannelMessageEditTest.java	Replaced publishes with publishWithResult/publishAsync; tests use PublishResult.serials[0]; added polling error handling for 404 during waits.
Build & CI .github/workflows/integration-test.yml, java/build.gradle.kts	Switched Java distribution from corretto to temurin; increased test retry maxFailures from 8 to 15.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Client
participant Channel as ChannelBase
participant Transport as Http/ConnectionManager
participant Server
participant CallbackHandler as Callback
Client->>Channel: publishWithResult / publishAsync(...)
Channel->>Transport: build & send publish request (publishImpl)
Transport->>Server: HTTP/WebSocket publish
Server-->>Transport: Response (PublishResult payload)
Transport-->>Channel: deliver PublishResult
Channel-->>CallbackHandler: invoke onSuccess(publishResult) / onError(err)
CallbackHandler-->>Client: handle result

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🐰 I hopped through types and callbacks new,

serials now return in a neat queue,
PublishResult tucked in my paw,
tests fetch serials without a flaw,
tiny rabbit cheers — hooray for you! 🥕🎉

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 59.46% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Linked Issues check	❓ Inconclusive	The linked issue AIT-84 has no description or requirements provided to validate against the PR changes.	Provide detailed requirements or acceptance criteria from the linked issue AIT-84 to validate PR compliance.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately summarizes the main change: adding support for returning serials on publish operations.
Out of Scope Changes check	✅ Passed	All changes are scoped to implementing publish result serialization: new PublishResult APIs, generic ToCallback refactoring, deprecations, and corresponding test updates align with the stated objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch AIT-84/message-publish-result

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In
`@lib/src/test/java/io/ably/lib/test/realtime/RealtimeChannelMessageEditTest.java`:
- Around line 131-139: The test creates a Helpers.AsyncWaiter<PublishResult>
named publishResultAsyncWaiter but never passes it to channel.publish(), so
publishResultAsyncWaiter.waitFor() blocks; fix by calling channel.publish(...)
with publishResultAsyncWaiter as the callback parameter (i.e., pass
publishResultAsyncWaiter or its callback method into the channel.publish
invocation used to publish the "test_event" so PublishResult is delivered and
waitFor() can complete), then use publishResultAsyncWaiter.result to assert
serials.

🧹 Nitpick comments (2)

lib/src/test/java/io/ably/lib/test/rest/RestChannelMessageEditTest.java (1)

62-63: Consider adding null safety for serials array.

PublishResult.serials is annotated as @Nullable. Accessing publishResult.serials[0] directly risks an NPE if the server returns a null serials array. Consider asserting serials != null first:

assertNotNull("Expected serials array", publishResult.serials);
assertNotNull("Expected message to have a serial", publishResult.serials[0]);

This pattern should be applied consistently throughout the test file.

lib/src/main/java/io/ably/lib/realtime/ChannelBase.java (1)

447-455: Consider renaming for clarity.

The method is named callCompletionListenerError but accepts a Callback<PublishResult> parameter. Consider renaming to callCallbackError or similar to avoid confusion with the existing CompletionListener-based overload at line 437.

♻️ Suggested rename

-    private static void callCompletionListenerError(Callback<PublishResult> listener, ErrorInfo err) {
+    private static void callCallbackError(Callback<PublishResult> listener, ErrorInfo err) {

[Copilot]

Pull request overview

This pull request adds support for returning message serials from publish operations. It introduces new publishWithResult and publishAsync APIs that return PublishResult objects containing message serials, and deprecates older CompletionListener-based methods in favor of Callback<PublishResult>.

Changes:

• Introduced publishWithResult synchronous API that returns PublishResult with message serials
• Added new publishAsync methods accepting Callback<PublishResult> for asynchronous publishing with typed results
• Deprecated CompletionListener-based publish methods in favor of callback-based variants with better type safety

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
lib/src/main/java/io/ably/lib/rest/ChannelBase.java	Added publishWithResult and publishAsync(Callback<PublishResult>) methods; deprecated older CompletionListener variants
lib/src/main/java/io/ably/lib/realtime/ChannelBase.java	Added new publish methods with Callback<PublishResult> parameter; deprecated CompletionListener variants
lib/src/main/java/io/ably/lib/realtime/CompletionListener.java	Made ToCallback generic to support different result types
lib/src/main/java/io/ably/lib/push/PushBase.java	Updated to use generic ToCallback<> with type parameter
android/src/main/java/io/ably/lib/push/PushChannel.java	Updated to use generic ToCallback<> with type parameter
lib/src/test/java/io/ably/lib/test/rest/RestChannelMessageEditTest.java	Updated tests to use publishWithResult and publishAsync with callback
lib/src/test/java/io/ably/lib/test/realtime/RealtimeChannelTest.java	Simplified publish calls by removing explicit null listeners
lib/src/test/java/io/ably/lib/test/realtime/RealtimeChannelMessageEditTest.java	Updated tests to use async publish with PublishResult callback

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sacOO7]

lgtm