Expose MQTT publish metadata to custom payload formatters

[Hanabi9248]

Description

Fixes #18625.

Pass the complete MQTT publication to custom payload formatters so they can use the client ID, username and QoS alongside the topic and payload.

The new formatMessage(InterceptPublishMessage) default method delegates to format(String, ByteBuf), which retains the existing payload-only fallback. Existing formatters need no changes. A separate method name also avoids making existing format(null) calls ambiguous. The broker still owns and releases the payload; the customization guide documents its lifetime.

Tests

On JDK 25, the 30-module Maven reactor build and all 11 MQTT tests passed:

mvn -pl external-service-impl/mqtt -am test \
  -Dtest=PayloadFormatterContextTest,JSONPayloadFormatterTest,LinePayloadFormatterTest \
  -Dsurefire.failIfNoSpecifiedTests=false

The new tests cover payload-only and topic-aware formatters, handler dispatch, and payload release when a formatter returns or throws. Both handler tests fail when run against the old handler. Cluster integration tests were not run.

• Added unit tests and updated the customization guide.
• Added Javadoc for the new callback.

[Copilot]

🟢 Approval recommended

The implementation is backward-compatible, documented, and adequately tests payload lifecycle and dispatch behavior.

Pull request overview

Exposes MQTT publication metadata to custom payload formatters while preserving backward compatibility.

Changes:

• Adds a metadata-aware formatter callback.
• Passes full publications through the handler.
• Documents and tests dispatch and payload ownership.

File summaries

File	Description
PayloadFormatter.java	Adds the backward-compatible callback.
MPPPublishHandler.java	Dispatches complete publications.
PayloadFormatterContextTest.java	Tests delegation, dispatch, and release behavior.
README.md	Documents metadata access and payload lifetime.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.