Add MessageExtras support to PresenceMessage

[AndyTWF]

Summary

This change adds full support for MessageExtras on presence messages:

1. PresenceMessage.extras field (TP3i) — allows presence messages to carry arbitrary metadata and ancillary payloads, with serialization support in both MessagePack and JSON formats.
2. Extras parameter on convenience methods — adds MessageExtras overloads to enter(), update(), leave() and their *Client variants so callers can pass extras without dropping down to updatePresence(PresenceMessage, CompletionListener).
3. Bug fix: re-enter preserves extras (RTP17g) — enterInternalMembers() now passes item.extras through when automatically re-entering after reconnect, where previously extras were dropped.

CHA-1243

Prerequisite to ably/ably-chat-kotlin#193

Closes #736
Closes #753

Key Changes

PresenceMessage.java

• Added extras field of type MessageExtras (TP3i)
• Added 4-arg constructor: PresenceMessage(Action, String, Object, MessageExtras); existing 3-arg constructor delegates to it with extras = null
• Updated clone() to copy the extras field
• Serialization support for extras in both MessagePack (writeMsgpack/readMsgpack) and JSON (read/Serializer) formats
• JSON deserialization includes type checking to ensure extras is a valid JSON object

Presence.java

• 6 new overloaded public methods with MessageExtras extras parameter:
  • enter(Object data, MessageExtras extras, CompletionListener listener) — RTP8
  • update(Object data, MessageExtras extras, CompletionListener listener) — RTP9
  • leave(Object data, MessageExtras extras, CompletionListener listener) — RTP10
  • enterClient(String clientId, Object data, MessageExtras extras, CompletionListener listener) — RTP15
  • updateClient(String clientId, Object data, MessageExtras extras, CompletionListener listener) — RTP15
  • leaveClient(String clientId, Object data, MessageExtras extras, CompletionListener listener) — RTP15
• Existing methods delegate to the new overloads with null extras (fully backward-compatible, no ambiguity — different arity)
• enterClientWithId() now accepts and passes through MessageExtras
• Bug fix: enterInternalMembers() passes item.extras on re-enter (RTP17g)

RealtimePresenceTest.java

• presence_enter_with_extras — existing test for extras via updatePresence() directly
• presence_enter_with_extras_convenience — new: tests enter(data, extras, listener)
• presence_update_with_extras — new: tests update(data, extras, listener)
• presence_leave_with_extras — new: tests leave(data, extras, listener)
• presence_enterClient_with_extras — new: tests enterClient(clientId, data, extras, listener)

Backward Compatibility

All changes are fully backward-compatible. No existing method signatures change. Java overload resolution is clean since the new methods differ in arity from the existing ones.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Presence operations now support attaching optional metadata ("extras") to enter, update, and leave actions, including for specific client IDs. Presence messages will carry and return extras where provided.
• Tests
  • Added tests verifying extras are sent, received, and included in completion callbacks.
• Compatibility
  • Backward compatible: existing presence methods retain previous behavior.

[coderabbitai]

Warning

Rate limit exceeded

@AndyTWF has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 20 minutes and 54 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

Walkthrough

Adds MessageExtras support to Presence APIs and PresenceMessage: new overloads for enter/update/leave (including clientId variants), PresenceMessage gains an extras field and serialization handling, tests added, and Kotlin adapter/interface updated to accept and forward extras.

Changes

Cohort / File(s)	Summary
Presence API (Java) lib/src/main/java/io/ably/lib/realtime/Presence.java	Added public overloads accepting MessageExtras for enter, update, leave and clientId variants; existing overloads delegate to new methods. Internals updated to propagate extras into PresenceMessage construction and enter flows.
PresenceMessage model (Java) lib/src/main/java/io/ably/lib/types/PresenceMessage.java	Added public MessageExtras extras field and EXTRAS constant; new constructor with extras; updated clone(), msgpack read/write, JSON read/serialize, and added deserializer to include extras in serialization/deserialization.
Tests (Java) lib/src/test/java/io/ably/lib/test/realtime/RealtimePresenceTest.java	Added tests validating extras propagation for enter/update/leave and enterClient; assertions check echoed extras and completion callbacks.
Kotlin public API (pubsub-adapter) pubsub-adapter/src/main/kotlin/com/ably/pubsub/RealtimePresence.kt	Updated interface signatures to accept optional extras: MessageExtras? for enter/update/leave and clientId variants; Javadoc updated accordingly.
Kotlin adapter implementations pubsub-adapter/src/main/kotlin/io/ably/lib/realtime/RealtimePresenceAdapter.kt	Updated overrides to accept extras: MessageExtras? and forward it to underlying Java presence methods.

Sequence Diagram

sequenceDiagram
    participant Client as Client
    participant Presence as Presence
    participant PM as PresenceMessage
    participant Network as Network/Server

    Client->>Presence: enter(data, extras, listener)
    Presence->>Presence: enterClientWithId(..., extras)
    Presence->>PM: new PresenceMessage(action, clientId, data, extras)
    PM->>PM: store extras field
    Presence->>Network: serialize PresenceMessage (includes extras)
    Network-->>Presence: deliver PresenceMessage JSON/msgpack
    Presence->>PM: deserialize (reads extras)
    Presence-->>Client: emit PresenceMessage(with extras)
    Client->>Client: listener.onSuccess()

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 A hop with a pouch full of extras bright,
I tuck small claims in each presence light,
Enter, update, leave — a merry dance,
Messages carry a richer chance,
Hooray — presence now has extra delight! 🎉

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 63.04% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding MessageExtras support to PresenceMessage, which is the primary feature across all modified files.
Linked Issues check	✅ Passed	PR successfully addresses all linked issues: #736 adds extras field to PresenceMessage, #753 adds extras parameter to all presence methods (enter, update, leave, enterClient, updateClient, leaveClient), and CHA-1243 exposes extras for user claims access.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to adding MessageExtras support: PresenceMessage enhancements, Presence API overloads, Kotlin adapter updates, and comprehensive test coverage are all within defined objectives.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/add-extras-presence-message-3bEeo

---

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/main/java/io/ably/lib/types/PresenceMessage.java`:
- Around line 293-309: The read method in PresenceMessage currently throws when
extras is the JSON literal null; update PresenceMessage.read to treat JsonNull
as absent by checking extrasElement.isJsonNull() (or instanceof JsonNull) and
skipping the extras parsing instead of erroring, so only non-null JsonObject
values are passed to MessageExtras.read; reference the EXTRAS lookup, the
extrasElement variable, and MessageExtras.read when making this change.