chore: add @Blocking and @NonBlocking annotations

[ttypic]

Added @Blocking and @NonBlocking annotations for better documentation

Summary by CodeRabbit

• Chores
  • Added blocking behavior metadata annotations to channel operations (attachment, detachment, subscription, history retrieval, messaging) and authentication methods to improve code documentation and clarity.

[coderabbitai]

Walkthrough

The changes add JetBrains @Blocking and @NonBlocking annotations to multiple public methods across three files in the Ably Java client library. These annotations indicate threading model expectations for authentication, channel operations, and subscription management without modifying method logic or signatures.

Changes

Cohort / File(s)	Summary
Realtime Channel Operations lib/src/main/java/io/ably/lib/realtime/ChannelBase.java	Added @NonBlocking annotations to channel lifecycle methods (attach, detach), subscription methods (subscribe/unsubscribe variants), async history retrieval, and option updates. Added @Blocking to synchronous history and message retrieval operations.
Authentication Operations lib/src/main/java/io/ably/lib/rest/Auth.java	Added @Blocking annotations to authorization and token request methods (authorize, authorise, requestToken, createTokenRequest). Added @NonBlocking to token renewal methods (renew, renewAuth). Includes import statements for blocking annotations.
REST Channel Operations lib/src/main/java/io/ably/lib/rest/ChannelBase.java	Added @Blocking annotations to synchronous history and presence methods. Added @NonBlocking annotations to async variants (publishAsync, historyAsync, Presence.getAsync, Presence.historyAsync).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 Hop, hop—annotations bloom,
Blocking paths and async rooms,
Methods now wear threading threads,
Clear intent where flow is led! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding @Blocking and @NonBlocking annotations to multiple methods across three files for improved documentation.
Docstring Coverage	✅ Passed	Docstring coverage is 96.55% which is sufficient. The required threshold is 80.00%.

_{✏️ 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 feat/add-blocking-annotations

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

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]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

lib/src/main/java/io/ably/lib/rest/Auth.java (1)

1019-1024: ⚠️ Potential issue | 🟠 Major

@NonBlocking on renew() is incorrect — the method blocks on HTTP I/O.

renew() synchronously calls assertValidToken(...) (line 1021), which internally calls requestToken(...) — a method you've annotated @Blocking because it performs HTTP requests. This makes renew() a blocking method.

The same issue applies to renewAuth() on line 1034–1038: it also synchronously calls assertValidToken(...) before dispatching the async part.

Both should be @Blocking.

Proposed fix

     `@Deprecated`
-    `@NonBlocking`
+    `@Blocking`
     public TokenDetails renew() throws AblyException {

-    `@NonBlocking`
+    `@Blocking`
     public void renewAuth(RenewAuthResult result) throws AblyException {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/src/main/java/io/ably/lib/rest/Auth.java` around lines 1019 - 1024, The
`@NonBlocking` annotation on renew() (and likewise on renewAuth()) is incorrect
because renew() calls assertValidToken(...), which invokes requestToken(...) and
performs HTTP I/O; change the annotation to `@Blocking` for renew() and
renewAuth() so their declared blocking behavior matches the synchronous HTTP
calls — update the annotations on the methods renew() and renewAuth() (and any
related javadoc/comments) to `@Blocking` and ensure no `@NonBlocking` remains on
those methods that call assertValidToken(...) / requestToken(...).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@lib/src/main/java/io/ably/lib/rest/Auth.java`:
- Around line 1019-1024: The `@NonBlocking` annotation on renew() (and likewise on
renewAuth()) is incorrect because renew() calls assertValidToken(...), which
invokes requestToken(...) and performs HTTP I/O; change the annotation to
`@Blocking` for renew() and renewAuth() so their declared blocking behavior
matches the synchronous HTTP calls — update the annotations on the methods
renew() and renewAuth() (and any related javadoc/comments) to `@Blocking` and
ensure no `@NonBlocking` remains on those methods that call assertValidToken(...)
/ requestToken(...).