[mdns]: Refactor stage #1

[david-cermak]

MDNS Component Refactor

Introduction

The MDNS component has been refactored from a single monolithic file mdns.c into a set of focused modules with clear responsibilities. This restructuring maintains the same functionality while improving code organization, maintainability, and testability.

The refactor has been performed in thee major stages, to ensure smooth transition to production while avoiding major changes in untested paths. These stages are:

• Restructuring into several modules while keeping the actual code changes to minimum
• Cover functionality of each module by specifically focused unit tests.
• Optimizations on module levels (string and queue operations, esp_timer dependency, socket task improvements, error checking)

Module Structure

mdns_service.c

The central service module that orchestrates the MDNS component operation. It manages the service task, timer, action queue, and system event handling. This module provides the entry points for the public API and coordinates actions between different modules. It's responsible for the general lifecycle of the MDNS service.

mdns_responder.c

Implements the responder functionality that answers incoming MDNS queries. It manages hostname and service registration, and generates appropriate response packets based on the queried information. The responder tracks all registered services and their associated metadata, handling hostname conflicts and service announcement.

mdns_browser.c

Handles browse/query functionality, managing browse requests for MDNS services on the network. It provides the infrastructure for adding, tracking, and removing browse requests, and processes incoming service discovery responses. The module manages browsing state and notifies applications when services appear or disappear.

mdns_querier.c

Handles outgoing query functionality, maintaining state for ongoing queries and processing query responses. It supports one-shot and continuous queries, manages query timeouts, and organizes results. The module provides the infrastructure for applications to discover services and resolve hostnames.

mdns_send.c

Manages packet generation and transmission. It constructs properly formatted MDNS packets, with correct headers and resource records, and handles the transmission scheduling and queueing of outgoing messages. This module encapsulates knowledge about the MDNS protocol packet structure.

mdns_receive.c

Processes incoming MDNS packets, parsing and validating their structure. It extracts queries and responses from received packets and dispatches them to the appropriate handling modules. This module focuses on packet parsing and initial classification.

mdns_pcb.c

Manages protocol control blocks (PCBs) that handle the state machine for MDNS interface operation. It coordinates the probing, announcing, and running states for each network interface and protocol combination. This module is responsible for service conflict detection, duplicate interface handling, and ensuring proper service announcements.

mdns_networking_lwip.c and mdns_networking_socket.c

These modules provide networking abstraction for different underlying network stacks. They handle multicast group management, packet reception, and transmission over the network interfaces. This abstraction allows the MDNS implementation to work with different networking stacks.

mdns_netif.c

Manages network interface registration and monitoring. It tracks network interface state changes and notifies the MDNS service when interfaces become available or unavailable, enabling dynamic adaptation to network configuration changes.

mdns_utils.c

Contains common utility functions used across multiple modules, such as string handling, data structure operations, and debug helpers. This module centralizes shared functionality to avoid code duplication.

mdns_mem_caps.c

Provides memory allocation functions with capability-based allocation support. It encapsulates memory management operations, making it easier to track and debug memory usage across the MDNS component.

mdns_debug.c

Contains debugging and logging utilities specific to the MDNS component. It provides structured logging and debug information for troubleshooting complex MDNS operations.

Testability Improvements

The refactored module structure significantly enhances testability by clearly separating different functional areas. Each module can now be tested in isolation with proper mocking of its dependencies. The separation of networking, packet handling, and business logic makes it possible to create focused unit tests without the complexity of managing the entire MDNS stack. Module-specific state is now contained within individual modules rather than distributed throughout a monolithic codebase, making test case setup and verification more straightforward. The refactoring also improves the ability to simulate various network conditions and edge cases by intercepting inter-module communication at well-defined boundaries.

Conclusion

The MDNS component refactoring provides a more maintainable and testable architecture while preserving the existing public API. By breaking down the monolithic implementation into focused modules with clear responsibilities, the codebase becomes easier to understand, extend, and maintain. The refactored structure makes it simpler to identify and fix bugs, implement new features, and adapt to future requirements. This architectural improvement supports long-term evolution of the component while maintaining backward compatibility for existing applications.

Adding fuzzer tests

• example of a failed job https://github.com/espressif/esp-protocols/actions/runs/13990422842/job/39172942586 (with artifacts containing crashes)
• example of a passing job https://github.com/espressif/esp-protocols/actions/runs/13990767171/job/39173999992?pr=776

[zwx1995esp]

For the whole architecture, LGTM. I reviewed only for mdns_service.c and mdns_utils.c and left some nits and questions. For the other files, I will finish this weekend.

[zwx1995esp]

Question: what is the difference between this function and mdns_utils_append_u16?

[david-cermak]

the append function is supposed to be used when composing a packet, so it keeps track of the current pointer and returns the position.

[zwx1995esp]

Ok, I just see the implementation of the two function are much the same, can we use the function mdns_utils_append_u16 for both set and append scenario?

[david-cermak]

Good point, but i'd again leave it for phase III, where we can address optimizations. I'd keep it here as is, just to reduce the complexity of this PR