How quicr/libquicr works
Project type and purpose
• libquicr is a C++ API library implementing a publish/subscribe protocol (draft-ietf-moq-transport-04).
• It provides both client-side and server-side (relay) APIs, plus example executables (qclient, qserver), benchmarks (qperf/qperf2), tests, and a draft-parser tool.
File structure to extract the architecture
• Top-level executables in cmd/: qserver (relay), qclient examples, qperf/qperf2 (benchmarks).
• Core library under include/quicr and src/:
• API layer (client.h, server.h, common.h, config.h)
• Control-message subsystem (ctrl_message_types, ctrl_messages)
• Track handlers (publish_fetch, publish_track, fetch_track, subscribe_track, joining_fetch)
• Storage & scheduling (data_storage, safe_queue, time_queue, priority_queue)
• Transport abstraction (quic_transport, transport_picoquic)
• Utilities (hash, uintvar, metrics).
• External dependencies: mbedTLS/BoringSSL, picoquic/picotls, spdlog, doctest, Python/Jinja (draft_parser).
README for additional insights
• Describes Client/Server examples (qclient, qserver) and usage.
• Mentions the relay pattern: server accepts connections and relays objects to subscribers.
• Highlights TLS (cert/key) for server, build & test targets.
Main components
• qserver executable (uses Server API)
• qclient executable (uses Client API; can publish, subscribe, or both)
• qperf/qperf2 (benchmark clients)
• draft_parser (tool to generate code from protocol drafts)
• API layer: Client API, Server API
• Control Message Processor: control message parsing and dispatch
• Track Handlers: publish, subscribe, fetch, joining
• Storage & Queues: data_storage, time_queue, safe_queue, priority_queue
• Transport Abstraction: quic_transport interface
• QUIC stack: picoquic + picotls
• TLS library: mbedTLS or BoringSSL
d. External/support services
• Metrics (spdlog)
• Testing (doctest)
• Codegen (Python + Jinja templates for tools/draft_parser)
Relationships and interactions
• Client API → Control Message Processor → Transport Abstraction → QUIC/TLS → Network → Server transport
• Server transport → Control Message Processor → Track Handlers → Data Storage/Queues
• Publish path: Client publishes → control/data messages over QUIC → server’s publish handler → data_storage → dispatch to subscriber handlers → back over QUIC to clients
• Subscribe path: Client subscribes → control message → server’s subscribe handler → storage lookup or queued messages → data stream to client
• Benchmarks drive the same paths at scale; draft_parser is a separate offline code-generation tool.
Architectural patterns and design principles
• Layered architecture: clear separation of API, message handling, storage, transport, and external libs.
• Publish-subscribe messaging pattern implemented via track handlers and data storage.
• Abstraction of transport so the same API works over different QUIC/TLS implementations.
• Asynchronous/event-driven design using tick_service/time_queue.
• Single Responsibility Principle: each module (handler, storage, transport) has a focused role.
Elements
• Blue rectangles for library modules
• Green rectangles for external libraries
• Grey rectangles for executables/tools