Inconsistent QUIC Support: MqttClient lacks QUIC handling, while MqttQuicClient/Listener are standalone. How to use QUIC as transport?

[VitaliyNazarov]

Вот готовый текст issue на английском, который вы можете скопировать и опубликовать в репозитории NewLife.MQTT на GitHub. Я постарался сформулировать его четко, конструктивно и с конкретными предложениями по улучшению, чтобы привлечь внимание автора.

Issue Title: Inconsistent QUIC Support: MqttClient lacks QUIC handling, while MqttQuicClient/Listener are standalone. How to use QUIC as transport?

---

Description

I'm evaluating NewLife.MQTT for a project that requires reliable communication over unstable networks (e.g., 3G/satellite) and I'm very interested in the MQTT over QUIC feature. However, after studying the repository and code, I found the current implementation of QUIC support confusing and inconsistent with the documentation.

Steps to Reproduce / Observed Behavior

1. Documentation: The README.md clearly states that QUIC is one of the six supported transport protocols and provides an example:

   new MqttClient { Server = "quic://broker.example.com:14567" };         // QUIC (.NET 7+)

2. Codebase (MqttClient): However, the MqttClient class code does not contain any logic to handle a "quic://" scheme. The URI parsing and connection logic in the main MqttClient appears to be built around TCP/WebSocket transports.

3. Separate Classes: There are separate classes, MqttQuicClient and MqttQuicListener (under the Quic namespace), that provide a raw QUIC transport layer. These classes are not integrated with or used by the main MqttClient or MqttServer. They seem to be a parallel, low-level implementation.

Expected / Desired Behavior

1. MqttClient and MqttServer should natively support the "quic://" scheme as advertised. The MqttClient should be able to establish a full MQTT session over a QUIC connection when the Server property is set to a quic:// address, likely using MqttQuicClient internally.

2. A clear and unified API. The main entry points for MQTT functionality should be the primary MqttClient and MqttServer classes. The underlying transport (TCP, TLS, WebSocket, QUIC) should be an implementation detail managed by the library and chosen via the URI scheme. The current decoupling makes the library harder to adopt for users who specifically want QUIC.

3. Documentation should match the code. The README.md should either be updated to reflect the current state (e.g., explaining that QUIC support is still experimental or requires using separate classes) or, ideally, a guide on how to integrate the existing MqttQuicClient with the main MqttClient framework should be provided.

Suggested Solutions / Proposals

1. Integrate MqttQuicClient and MqttQuicListener into the main MqttClient/MqttServer lifecycle. This would make QUIC a seamless transport option.

2. Provide a clear example in the documentation or a wiki page demonstrating how to use the current MqttQuicClient to establish an MQTT session. For instance, explaining how to wrap the raw QUIC stream with MQTT message encoding/decoding would be helpful.

3. If the QUIC implementation is intended as a transport layer for the main classes but is incomplete, please clarify its status. This will help the community understand if it's ready for production use or still a work-in-progress.

Conclusion

The core issue is a mismatch between the advertised features and the actual codebase, which creates a significant barrier for new users interested in the key QUIC feature. Clarifying and unifying this support would greatly enhance the usability and value of this excellent library. Thank you for your work on NewLife.MQTT.

[nnhy]

新增 QUIC 传输支持，完善客户端/服务端能力 · d1f341f
d1f341f

[VitaliyNazarov]

新增 QUIC 传输支持，完善客户端/服务端能力 · d1f341f d1f341f

太好了！谢谢你的快速回复。