mqtt: add new experimental protocol

Closes #5173

docs/EXPERIMENTAL.md

@@ -20,3 +20,4 @@ Experimental support in curl means:
 
  - HTTP/3 support and options
  - alt-svc support and options
+ - MQTT

docs/FEATURES

@@ -180,6 +180,9 @@ IMAPS (*1)
  - explicit "STARTTLS" usage to "upgrade" plain imap:// connections to use SSL
  - via http-proxy
 
+MQTT
+ - Subscribe to and publish topics using url scheme mqtt://broker/topic
+
 FOOTNOTES
 =========
 

docs/MQTT.md

@@ -0,0 +1,61 @@
+# MQTT in curl
+
+## Experimental!
+
+MQTT support in curl is considered **EXPERIMENTAL** until further notice. It
+needs to be enabled at build-time. See below.
+
+After the initial merge, further development and tweaking of the MQTT support
+in curl will happen in the master branch using pull-requests, just like
+ordinary changes.
+
+Experimental support for MQTT means that we **do not guarantee** that the
+current protocol functionality will remain or remain this way going forward.
+There are no API or ABI promises for experimental features as for regular curl
+features.
+
+Do not ship anything with this enabled.
+
+## Build
+
+    ./configure --enable-mqtt
+
+## Usage
+
+A plain "GET" subscribes to the topic and prints all published messages.
+Doing a "POST" publishes the post data to the topic and exits.
+
+Example subscribe:
+
+    curl mqtt://host/home/bedroom/temp
+
+Example publish:
+
+    curl -d 80 mqtt://host/home/bedroom/dimmer
+
+## What does curl deliver as a response to a subscribe
+
+It outputs two bytes topic length (MSB | LSB), the topic followed by the
+payload.
+
+## Caveats
+
+Remaining limitations:
+ - No username support
+ - Only QoS level 0 is implemented for publish
+ - No way to set retain flag for publish
+ - No username/password support
+ - No TLS (mqtts) support
+ - Naive EAGAIN handling won't handle split messages
+
+## Work
+
+1. Write a mqtt server for the test suite
+2. Create a few tests verifying the existing mqtt functionality
+3. Work on fixing some of the worst limitations - with accompanying tests
+4. Consider replacing the client-side MQTT code with wolfMQTT
+
+## Credits
+
+The initial MQTT patch was authored by Björn Stenberg. This work is built upon
+that patch and has been expanded since.

docs/Makefile.am

@@ -71,6 +71,7 @@ EXTRA_DIST =                                    \
  KNOWN_BUGS                                     \
  LICENSE-MIXING.md                              \
  MAIL-ETIQUETTE                                 \
+ MQTT.md                                        \
  PARALLEL-TRANSFERS.md                          \
  README.md                                      \
  RELEASE-PROCEDURE.md                           \

docs/cmdline-opts/data.d

@@ -2,7 +2,7 @@ Long: data
 Short: d
 Arg: <data>
 Help: HTTP POST data
-Protocols: HTTP
+Protocols: HTTP MQTT
 See-also: data-binary data-urlencode data-raw
 Mutexed: form head upload-file
 ---

docs/cmdline-opts/page-header

@@ -31,8 +31,8 @@ curl \- transfer a URL
 .B curl
 is a tool to transfer data from or to a server, using one of the supported
 protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP,
-LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET
-and TFTP). The command is designed to work without user interaction.
+LDAPS, MQTT, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS,
+TELNET and TFTP). The command is designed to work without user interaction.
 
 curl offers a busload of useful tricks like proxy support, user
 authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer

docs/libcurl/opts/CURLINFO_PROTOCOL.3

@@ -38,7 +38,7 @@ CURLPROTO_IMAPS, CURLPROTO_LDAP, CURLPROTO_LDAPS, CURLPROTO_POP3,
 CURLPROTO_POP3S, CURLPROTO_RTMP, CURLPROTO_RTMPE, CURLPROTO_RTMPS,
 CURLPROTO_RTMPT, CURLPROTO_RTMPTE, CURLPROTO_RTMPTS, CURLPROTO_RTSP,
 CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_SMB, CURLPROTO_SMBS, CURLPROTO_SMTP,
-CURLPROTO_SMTPS, CURLPROTO_TELNET, CURLPROTO_TFTP
+CURLPROTO_SMTPS, CURLPROTO_TELNET, CURLPROTO_TFTP, CURLPROTO_MQTT
 .SH PROTOCOLS
 All
 .SH EXAMPLE

docs/libcurl/symbols-in-versions

@@ -676,6 +676,7 @@ CURLPROTO_IMAP                  7.20.0
 CURLPROTO_IMAPS                 7.20.0
 CURLPROTO_LDAP                  7.19.4
 CURLPROTO_LDAPS                 7.19.4
+CURLPROTO_MQTT                  7.71.0
 CURLPROTO_POP3                  7.20.0
 CURLPROTO_POP3S                 7.20.0
 CURLPROTO_RTMP                  7.21.0