Understanding Nacos Configuration Center Long‑Polling Mechanism

Today’s article introduces one of the core principles of Nacos configuration center – the long‑polling mechanism – and explains how it enables efficient configuration change detection.

On the client side, the NacosPropertySourceLocator creates a ConfigService instance via NacosFactory.createConfigService(), which uses reflection to instantiate NacosConfigService. The constructor starts a scheduled thread pool that periodically runs ClientWorker.checkConfigInfo(), checks local caches, and triggers long‑polling tasks.

public static ConfigService createConfigService(Properties properties) throws NacosException {
    //【断点步入】创建 ConfigService
    return ConfigFactory.createConfigService(properties);
}

The long‑polling task is built in ClientWorker, which creates two thread pools and schedules a LongPollingRunnable. This runnable iterates over CacheData entries, compares local MD5 hashes, and, if changes are detected, calls the server to fetch the updated configuration.

public void run() {
    List<CacheData> cacheDatas = new ArrayList();
    // iterate CacheData, check local config
    // request server for updates via MetricsHttpAgent.httpPost(...)
    // process changed data IDs and fetch new content
}

Key supporting classes include MetricsHttpAgent (handles HTTP POST/GET for /v1/cs/configs/listener and /v1/cs/configs), HttpResult, and the cache structure AtomicReference<Map<String, CacheData>> that stores listener state.

On the server side, the ConfigController.listener() endpoint receives long‑polling requests. It delegates to ConfigServletInner.doPollingConfig(), which creates a ClientLongPolling object and registers it with LongPollingService.addLongPollingClient(). The service holds the client in a queue, waits up to the configured timeout (default 30 s), and responds when a configuration change is detected.

When a change occurs, the server publishes a LocalDataChangeEvent. Earlier Nacos versions handled this via LongPollingService.onEvent(); newer versions use a Subscriber.onEvent() that triggers a DataChangeTask executed by a thread pool, which retrieves the new configuration and sends it back to the client.

Overall, the article maps the end‑to‑end flow: client initialization → long‑polling task scheduling → server request handling → event publishing → data retrieval, providing a comprehensive view of Nacos’ dynamic configuration listening architecture.