feat: add subscribeBatchSize option to batch SUBSCRIBE packets

[Sheile]

Overview

AWS IoT Core limits each SUBSCRIBE packet to a maximum of 8 topics.

A single SUBSCRIBE request has a quota of 8 subscriptions.
https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits

This PR adds a new subscribeBatchSize?: number option that lets users control how many topics are sent in each packet. When the total number of topics to subscribe exceeds this value, the client will automatically split them into multiple SUBSCRIBE packets of the specified size.

Usage

const options = {
  ...
  subscribeBatchSize: 8,  // If you attempt to subscribe to more than 8 topics without this option, AWS IoT Core will reject the SUBSCRIBE packet.
}
const mqttClient = mqtt.connect('mqtts://xxxxxx-ats.iot.ap-northeast-1.amazonaws.com:8883', options)
const topics = ['/dummy1', '/dummy2', '/dummy3', '/dummy4', '/dummy5', '/dummy6', '/dummy7', '/dummy8', '/dummy9']
mqttClient.subscribe(topics, {}, (err) => { console.log(`subscribe is finished with ${err}`) })

Discussion

The third argument of Client#subscribe is a callback that receives three parameters:

1. err
2. granted
3. packet (undocumented)

Because this option may split your subscriptions into multiple SUBSCRIBE packets, the third parameter is handled as follows:

• On success: the callback is invoked with the last packet.
• On failure: the callback is invoked with the failed packet.

Any thoughts on whether this callback behavior is OK, or suggestions for improving it?

[robertsLando]

@Sheile thanks for your PR! Giving that this is something specific to AWS iOT I'm wondering if it could make more sense to let users handle this theirself, I usually create a wrapper around mqtt client to handle every call to it, it's a design choice I use everywhere.

@mcollina what do you think?

[Sheile]

@robertsLando
Thanks for quick reply!

When calling Client#subscribe, User can split topics manually.
But, resubscribe in this client will send single SUBSCRIBE packet with all topics automatically.

Therefore, User can't use this client with 9 or more topics in AWS IoT Core.

[mcollina]

Lgtm

I’m ok with it.

[codecov]

Codecov Report

Attention: Patch coverage is 90.32258% with 3 lines in your changes missing coverage. Please review.

Project coverage is 81.68%. Comparing base (65def96) to head (58b1d44).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/lib/client.ts	88.46%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1995      +/-   ##
==========================================
+ Coverage   81.46%   81.68%   +0.21%     
==========================================
  Files          25       25              
  Lines        1565     1583      +18     
  Branches      366      368       +2     
==========================================
+ Hits         1275     1293      +18     
  Misses        199      199              
  Partials       91       91              

Flag	Coverage Δ
unittests	81.68% <90.32%> (+0.21%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.