feat(microservices): support per-handler qos in mqtt

[suuuuuuminnnnnn]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (not needed)

PR Type

What kind of change does this PR introduce?

• Bugfix
• Feature
• Code style update (formatting, local variables)
• Refactoring (no functional changes, no api changes)
• Build related changes
• CI related changes
• Other... Please describe:

What is the current behavior?

MQTT subscriptions are currently created using only the global subscribeOptions (including qos) when ServerMqtt binds handlers.
This means all patterns share the same QoS and there is no way to override QoS per handler/pattern.

Issue Number: #16239

What is the new behavior?

Handlers can now override the QoS used for their MQTT subscription by providing extras.qos on the pattern decorator.
If extras.qos is defined, it overrides only the qos field for that specific pattern; otherwise the global subscribeOptions behavior remains unchanged.

Example:

@EventPattern('alerts/critical', Transport.MQTT, { qos: 2 })
handleCriticalAlert(data: any) {
  // high priority - guaranteed delivery
}

@EventPattern('telemetry/metrics', Transport.MQTT, { qos: 0 })
handleMetrics(data: any) {
  // best-effort delivery
}

Does this PR introduce a breaking change?

• Yes
• No

Other information

Implementation details

• Per-pattern subscribe options are computed by merging the global subscribeOptions with handler extras,
  overriding only qos when extras.qos is defined.
• No behavior changes when extras.qos is not provided.

Tests

• Added/updated tests to verify:
  • extras.qos overrides global QoS for that pattern
  • patterns without extras.qos use the global subscribe options
  • multiple patterns can subscribe with different QoS values

How to verify

• Run the microservices test suite, or the specific MQTT spec added in this PR.

[coveralls]

Pull Request Test Coverage Report for Build c12742ef-743b-442c-9eb2-150835a5ac57

Details

• 4 of 4 (100.0%) changed or added relevant lines in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.004%) to 89.829%

---

Totals
Change from base Build 3e932a26-d0f7-4368-b102-196754d847cf:	0.004%
Covered Lines:	7463
Relevant Lines:	8308

---

💛 - Coveralls

[kamilmysliwiec]

Could you create a PR to the docs to reflect/showcase this feature?

[suuuuuuminnnnnn]

Thanks for the suggestion!

I’m happy to add docs, but before I open a PR: where would you prefer this to be documented?
My guess is either:

• the Microservices MQTT transport docs (mentioning that extras.qos can override the global subscribeOptions.qos per pattern), or
• an example snippet in the @EventPattern / @MessagePattern section for MQTT.

If you point me to the preferred page/section, I can prepare a small doc update that explains the behavior and includes a short example.

[kamilmysliwiec]

in the Microservices MQTT transport docs correct

[kamilmysliwiec]

just a tiny additional section somewhere at the bottom of the page would be nice