Understanding Nacos Configuration Center Long‑Polling Mechanism

Today we introduce one of the core principles of Nacos Config Center – the long‑polling mechanism – and demonstrate its practical use.

We treat the Nacos console and registration center as the Nacos server , while the business service we develop is the Nacos client . The long‑polling workflow starts from ConfigService instantiation.

1. Client long‑polling scheduling

The process begins at NacosPropertySourceLocator.locate() , then enters NacosFactory.createConfigService() where a ConfigService instance is created via reflection. The constructor of NacosConfigService starts the scheduled task.

public static ConfigService createConfigService(Properties properties) throws NacosException {
    //【Breakpoint】Create ConfigService
    return ConfigFactory.createConfigService(properties);
}

Inside ConfigFactory.createConfigService() the NacosConfigService object is instantiated using reflection.

1.2 Initialization of HttpAgent

The design of MetricsHttpAgent and ServerHttpAgent is shown in the following diagrams:

1.2.2 Initialization of ClientWorker

ClientWorker creates two thread‑pool executors and starts a scheduled task that checks configuration every 10 seconds.

1.3 Checking configuration changes

The LongPollingRunnable.run() method iterates over cached data, calls checkLocalConfig() to compare local files, and then invokes checkUpdateDataIds() to request the server for changes.

public void run() {
    List
cacheDatas = new ArrayList();
    // iterate CacheData, check local config
    Iterator var3 = ((Map)ClientWorker.this.cacheMap.get()).values().iterator();
    while (var3.hasNext()) {
        CacheData cacheData = (CacheData) var3.next();
        if (cacheData.getTaskId() == this.taskId) {
            cacheDatas.add(cacheData);
            try {
                ClientWorker.this.checkLocalConfig(cacheData);
                if (cacheData.isUseLocalConfigInfo()) {
                    cacheData.checkListenerMd5();
                }
            } catch (Exception var13) {
                ClientWorker.LOGGER.error("get local config info error", var13);
            }
        }
    }
    // request server for updates
    List
changedGroupKeys = ClientWorker.this.checkUpdateDataIds(cacheDatas, inInitializingCacheList);
    // process changed configs ...
}

2. Server‑side long‑polling

The Nacos server receives the request at ConfigController.listener() , which forwards to ConfigServletInner.doPollingConfig() . The core logic resides in LongPollingService.addLongPollingClient() , which wraps the request into a ClientPolling object and schedules it.

The server holds the request for up to 30 seconds; if no configuration change occurs, it returns after the timeout, otherwise it immediately sends the changed DataId , Group , and Tenant to the client.

2.4 Configuration change event handling

When a configuration is modified, the server publishes a LocalDataChangeEvent . The LongPollingService (pre‑1.3.1) or a Subscriber (post‑1.3.1) listens to this event and triggers a DataChangeTask to push the new configuration to the client.

3. Summary of code structure

NacosPropertySourceLocator.locate() – creates ConfigService

NacosFactory.createConfigService() – uses reflection to instantiate NacosConfigService

Executors.newScheduledThreadPool() – creates thread pools for polling

ClientWorker.checkConfigInfo() – schedules periodic checks

ClientWorker.checkLocalConfig() – compares local files

ClientWorker.checkUpdateDataIds() – contacts server for updates

MetricsHttpAgent.httpPost() – calls /v1/cs/configs/listener

MetricsHttpAgent.httpGet() – calls /v1/cs/configs

LongPollingRunnable.run() – runs client polling thread

LongPollingService.addLongPollingClient() – server‑side request handling

Through this detailed walkthrough, readers can understand how Nacos implements long‑polling for dynamic configuration updates on both client and server sides.