[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. Kotlin wrappers — updates the RealtimePresence interface and RealtimePresenceAdapter with the extras parameter (defaulting to null).
4. JSON null tolerance — PresenceMessage.read() now handles "extras": null gracefully instead of throwing.

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 handles null extras gracefully and type-checks for 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)

RealtimePresence.kt / RealtimePresenceAdapter.kt

• Added extras: MessageExtras? = null parameter to all 6 presence methods in the Kotlin interface and adapter

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 can include optional metadata ("extras") on enter, update, and leave, including client-specific calls; presence messages now carry extras and preserve them across serialization.

• Tests

  • Added comprehensive tests validating extras are sent, received, serialized/deserialized, and exposed in callbacks.

• Compatibility

  • Backward compatible: existing presence calls delegate to the extras-enabled variants.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ec7678e3-f640-449d-8971-c546754f1b1f

📥 Commits

Reviewing files that changed from the base of the PR and between a646200 and b29c8a1.

📒 Files selected for processing (3)

• lib/src/test/java/io/ably/lib/test/realtime/RealtimePresenceTest.java
• lib/src/test/java/io/ably/lib/types/PresenceMessageTest.java
• pubsub-adapter/src/main/kotlin/com/ably/pubsub/RealtimePresence.kt

---

Walkthrough

Adds MessageExtras support to presence APIs and PresenceMessage: new extras-accepting overloads for enter/update/leave (including clientId variants), PresenceMessage gains an extras field with serialization/deserialization support, Kotlin interfaces/adapters updated, and tests added (with a duplicated test block present).

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 their *Client variants; existing two-arg methods delegate to the new extras-enabled signatures; PresenceMessage constructed with extras.
PresenceMessage model (Java) lib/src/main/java/io/ably/lib/types/PresenceMessage.java	Added public MessageExtras extras and EXTRAS key; new 4-arg constructor; clone, msgpack read/write, JSON read/serialize/deserializer updated to preserve extras.
PresenceMessage tests (Java) lib/src/test/java/io/ably/lib/types/PresenceMessageTest.java	New test suite validating constructors, clone, JSON and MessagePack round-trips and extras handling (including invalid extras behavior).
Realtime presence tests (Java) lib/src/test/java/io/ably/lib/test/realtime/RealtimePresenceTest.java	Many new tests exercising presence extras across enter/update/leave and clientId variants, presence.get and REST history; note the diff contains a duplicated block of these tests.
Kotlin public API (pubsub-adapter) pubsub-adapter/src/main/kotlin/com/ably/pubsub/RealtimePresence.kt	Interface signatures updated to add optional extras: MessageExtras? overloads; existing convenience methods delegate to the new signatures.
Kotlin adapter implementations pubsub-adapter/src/main/kotlin/io/ably/lib/realtime/RealtimePresenceAdapter.kt	Adapter override methods updated to accept extras: MessageExtras? and forward them to underlying Java presence methods.
Other small changes Import additions across files	Added import io.ably.lib.types.MessageExtras where needed.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Presence
    participant PresenceMessage
    participant Network

    Client->>Presence: enter(data, extras, listener)
    Presence->>PresenceMessage: new PresenceMessage(action, clientId, data, extras)
    PresenceMessage-->>Presence: constructed (includes extras)
    Presence->>Network: serialize PresenceMessage (JSON/msgpack includes extras)
    Network-->>Presence: deliver PresenceMessage payload
    Presence->>PresenceMessage: deserialize/read (extract extras)
    Presence-->>Client: emit PresenceMessage (with extras)
    Client->>Client: listener.onSuccess()

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I hop in with extras snug and bright,
Tucking tiny truths into presence light.
Enter, update, leave — I carry more cheer,
Messages richer, now extras appear,
A joyful thump — presence holds what’s dear.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add MessageExtras support to PresenceMessage' accurately summarizes the primary change in the changeset, which adds extras field and method overloads across presence APIs.
Linked Issues check	✅ Passed	All code changes align with linked issues #736 and #753: PresenceMessage now includes extras field with serialization support [#736], and all six presence methods have extras-accepting overloads with backward-compatible delegation [#753].
Out of Scope Changes check	✅ Passed	All changes are scoped to presence extras support: PresenceMessage, Presence API, RealtimePresence/Adapter, and comprehensive tests. No unrelated modifications detected.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 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

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
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]

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.