How Nacos Implements Long‑Polling for Real‑Time Configuration Updates

Client‑Side Long‑Polling Mechanism

The analysis starts from ConfigService, which is created via NacosFactory.createConfigService(). This method uses reflection to instantiate NacosConfigService, where the long‑polling scheduled task is launched.

Inside NacosConfigService 's constructor, several components are initialized:

HttpAgent : MetricsHttpAgent and ServerHttpAgent are set up to handle HTTP communication.

ClientWorker : Its constructor creates two scheduled thread pools and starts a periodic task that checks configuration changes every 10 seconds.

The periodic task ClientWorker.checkConfigInfo() performs two main actions:

It checks local configuration files via checkLocalConfig() using the cacheMap (an AtomicReference<Map<String, CacheData>> storing listeners keyed by dataId/group/tenant).

It invokes checkUpdateDataIds() to request the server for possible changes.

The core of the long‑polling logic resides in LongPollingRunnable.run(). It iterates over cached CacheData, calls checkLocalConfig(), and then sends a long‑polling request to the server. If the server reports changes, the method retrieves the new configuration via getServerConfig() and updates the cache, triggering listener notifications.

public void run() {
    // iterate CacheData, check local config
    // send long‑polling request
    // process changed group keys
    // fetch new config and update cache
    // trigger events
}

Server‑Side Long‑Polling Mechanism

On the server, the entry point is ConfigController.listener(), which forwards the request to ConfigServletInner.doPollingConfig(). This method delegates to LongPollingService.addLongPollingClient(), encapsulating the client request into a ClientPolling object and handing it to the scheduler.

The scheduler creates a ClientLongPolling thread that implements the long‑polling timeout (default 30 s). If no configuration change occurs, the request is held until the timeout expires; otherwise, the server responds immediately with the changed DataId, Group, and Tenant.

MD5 comparison ( MD5Util.compareMd5()) determines whether the data has changed.

The response is sent via LongPollingService.sendResponse().

After handling, the server schedules the next long‑polling task with a 29.5 s delay using ConfigExecutor.scheduleLongPolling().

Configuration Change Event Handling

When a configuration is modified on the Nacos server, a LocalDataChangeEvent is published. In versions prior to 1.3.1, LongPollingService (extending AbstractEventListener) handled the event via onEvent(). From 1.3.2 onward, a Subscriber listens to the event and triggers a DataChangeTask executed by a thread pool.

The DataChangeTask.run() method retrieves the updated configuration and pushes it to the client through the long‑polling response mechanism.

Summary Diagram of Core Classes and Methods

The following list outlines the main flow: NacosPropertySourceLocator.locate() – initializes ConfigService. NacosFactory.createConfigService() – creates NacosConfigService via reflection. Executors.newScheduledThreadPool() – creates thread pools for scheduling. ClientWorker.checkConfigInfo() – periodic check for config changes. ClientWorker.checkLocalConfig() – compares local files. ClientWorker.checkUpdateDataIds() – contacts server for updates. MetricsHttpAgent.httpPost() – calls /v1/cs/configs/listener for long‑polling. MetricsHttpAgent.httpGet() – calls /v1/cs/configs to fetch changed config. LongPollingRunnable.run() – executes client‑side long‑polling loop. ConfigController.listener() – server receives long‑polling request. LongPollingService.addLongPollingClient() – registers client request. ClientLongPolling.run() – server‑side long‑polling execution. DataChangeTask.run() – processes configuration change events.

Key Takeaways

The long‑polling design in Nacos ensures efficient, near‑real‑time propagation of configuration changes without overwhelming the network, by keeping connections open for up to 30 seconds and only responding when updates occur. Understanding this flow helps developers troubleshoot config sync issues and extend Nacos for custom use cases.