Add Multipath TCP (MPTCP) support for listeners, bridges, libmosquitto and clients

[moroznah]

Add Multipath TCP (MPTCP) support

---

Summary

This PR adds opt-in Multipath TCP (RFC 8684) support across mosquitto, in four
logical commits:

Commit	Area	Change
1	lib	New MOSQ_OPT_MPTCP for mosquitto_int_option(); shared net__socket_stream() helper
2	broker	New per-listener config option mptcp true|false
3	clients	New --mptcp flag for mosquitto_pub, mosquitto_sub, mosquitto_rr
4	broker	New bridge config option bridge_mptcp true|false

MPTCP lets a single connection use several network paths at once (e.g. WiFi +
cellular, or two NICs), giving seamless failover between paths and potential
throughput aggregation without any change to the MQTT layer. This is
particularly useful for MQTT deployments on mobile/vehicular/IIoT clients with
redundant uplinks, and for broker-to-broker bridges over unreliable WANs.

Everything is opt-in and off by default. No behaviour changes unless the
new options are explicitly enabled. No new build dependencies.

Usage

Broker listener:

listener 1883
mptcp true

Bridge:

connection mybridge
address remote.example.com:1883
bridge_mptcp true

libmosquitto:

mosquitto_int_option(mosq, MOSQ_OPT_MPTCP, 1);

Clients:

mosquitto_sub --mptcp -h remote.example.com -t 'topic/#'

Platform support and fallback semantics

• Linux-only, kernel 5.6+ (and net.mptcp.enabled=1). All code paths are
  guarded with #if defined(__linux__), so Windows/macOS/BSD builds are
  byte-for-byte unaffected at the socket layer.
• On non-Linux platforms: MOSQ_OPT_MPTCP returns MOSQ_ERR_NOT_SUPPORTED;
  the mptcp/bridge_mptcp config options are accepted but ignored with a
  logged warning; the client --mptcp flag produces an error.
• On Linux kernels without MPTCP (or with it disabled): socket creation with
  IPPROTO_MPTCP fails with EINVAL/EPROTONOSUPPORT/ENOPROTOOPT and we
  fall back to plain TCP. The broker detects the fallback (see design
  notes) and logs a warning; the library falls back silently.
• An mptcp true listener remains fully compatible with plain-TCP clients:
  an MPTCP listening socket accepts both MPTCP and regular TCP connections,
  so enabling the option cannot lock out existing clients.

Design notes

Why substitute the protocol at socket() time instead of in getaddrinfo()
hints. Passing IPPROTO_MPTCP via ai_protocol is rejected by many libc
versions (getaddrinfo validates the protocol against its own tables). The
established pattern — the same one used by curl and iperf3 — is to resolve
addresses normally and substitute IPPROTO_MPTCP when creating the socket,
falling back to the resolved ai_protocol if the kernel refuses. That is what
the new net__socket_stream(domain, type, protocol, use_mptcp) helper in
lib/net_mosq.c does; it is the single place holding the fallback-errno
logic, and is shared by the client connect path (both the synchronous path and
the WITH_ADNS async path in net__try_connect_step2()) and the broker's
listener setup.

Fallback vs. hard failure. A hard failure on kernels without MPTCP would
make --mptcp/mptcp true undeployable in mixed fleets and would break
brokers on kernel downgrades. Silent fallback alone would mask
misconfiguration on the broker side, so the compromise is: clients fall back
silently (documented), while the broker verifies the created listener socket
with getsockopt(SOL_SOCKET, SO_PROTOCOL) and logs
Warning: MPTCP is not supported by the kernel, falling back to TCP. if the
socket is not actually MPTCP. The check costs one getsockopt per listener at
startup, only when mptcp true is set.

IPPROTO_MPTCP availability at build time. glibc only exposes
IPPROTO_MPTCP from 2.32. Since the value (262) is part of the kernel ABI and
cannot change, net_mosq.h defines it when missing, guarded by
#if defined(__linux__) && !defined(IPPROTO_MPTCP). <netinet/in.h> is
included first so the #ifndef test is evaluated against the system
definition and never conflicts with it. This keeps the feature buildable on
older distros whose kernels do support MPTCP.

Internal API change. net__try_connect() gains a trailing
bool use_mptcp parameter. This is an internal symbol (not exported in
linker.version), so there is no ABI impact on libmosquitto. Its only two
callers are updated: net__socket_connect() passes mosq->mptcp, and the
bridge round-robin primary-retry probe in src/bridge.c passes
context->mptcp. Choosing a parameter over a global keeps the function usable
from both broker and lib contexts.

Bridge wiring. bridge_mptcp is stored on struct mosquitto__bridge and
copied onto the bridge's connection context in bridge__new()
(new_context->mptcp = bridge->mptcp). Because the broker's bridge contexts
reuse the lib's struct mosquitto and connect through net__socket_connect(),
both the normal connect path and the primary-retry path use MPTCP
consistently with no bridge-specific socket code.

Public option numbering/ABI. MOSQ_OPT_MPTCP = 18 extends
enum mosq_opt_t at the end; existing values are untouched. The mptcp flag
is a new bool in struct mosquitto (internal, not part of the public ABI),
placed alongside tcp_nodelay. Old applications running against the new
library see no behavioural difference.

Interaction with existing socket options. TCP_NODELAY,
SO_KEEPALIVE/TCP_KEEPIDLE etc. are supported by the kernel's MPTCP socket
option layer on recent kernels; on older kernels where a particular option is
not yet supported on MPTCP sockets, the existing code paths already only log
a warning on setsockopt() failure, so behaviour degrades gracefully.

Reload semantics. Like socket_domain, the listener mptcp option is
skipped on config reload, because listener sockets are not recreated on
SIGHUP. bridge_mptcp follows normal bridge option handling (bridges are
recreated on reload).

Scope deliberately excluded. No MPTCP-specific tuning is exposed (path
manager, subflow limits, MPTCP_INFO): these are administered system-wide via
ip mptcp / sysctls and would bloat the config surface. WebSockets listeners
are unaffected in this PR (the option applies to the TCP socket under any
listener type on the broker side, since it is applied at socket() creation
for the listener). TLS works unchanged on top of MPTCP since it is purely
above the transport.

Documentation

• man/mosquitto.conf.5.xml: mptcp (listener section) and bridge_mptcp
  (bridge section) entries.
• man/common/option-mptcp.xml + references from mosquitto_pub.1.xml,
  mosquitto_sub.1.xml, mosquitto_rr.1.xml.
• include/mosquitto/libmosquitto_options.h: MOSQ_OPT_MPTCP API docs.
• mosquitto.conf: commented examples for mptcp and bridge_mptcp.
• Client --help output updated.

ChangeLog.txt intentionally not modified to avoid conflicts — happy to add
entries if preferred.

Testing performed

On Linux 6.18 (net.mptcp.enabled=1), Makefile build with
-Wall -Wextra -Wconversion, clean:

1. Listener: broker with mptcp true — ss -Mln shows the listening
   socket as MPTCP.
2. Client end-to-end: mosquitto_sub --mptcp + mosquitto_pub --mptcp —
   strace confirms socket(AF_INET, SOCK_STREAM, IPPROTO_MPTCP), ss -Mn
   shows the established connection as MPTCP on both ends, message delivered.
3. Interop: plain-TCP mosquitto_pub against the mptcp true listener —
   works unchanged.
4. Kernel fallback: with net.mptcp.enabled=0, client --mptcp falls
   back (strace: IPPROTO_MPTCP → ENOPROTOOPT → IPPROTO_TCP, publish
   succeeds); broker logs the fallback warning and serves TCP.
5. Bridge: two brokers, B with mptcp true listener, A with
   bridge_mptcp true — ss -Mn shows the bridge connection as MPTCP;
   messages flow across the bridge.
6. Config validation: mptcp notabool → proper
   Error: Invalid 'mptcp' value at startup; options on non-listener/bridge
   context rejected by the existing REQUIRE_* macros.

Checklist

• Commits signed off (Signed-off-by, DCO), email matches Eclipse account
• ECA signed
• Based on and targeting develop
• Four small, self-contained commits
• Linux-only code guarded; other platforms unaffected
• Man pages, header docs, example config updated