alibaba--nacos/specs/en/plugin/control-plugin-spec.md

Control Plugin Spec

Scope

The control plugin type provides runtime traffic and connection control for Nacos server nodes. It covers connection admission, TPS checks, rule parsing, rule storage, and optional metrics collection.

This is a configured single-service plugin. The configured control manager type selects one ControlManagerBuilder. If no type is configured or the selected plugin cannot be loaded, Nacos uses no-limit default managers. Common lifecycle and state rules are defined by the Nacos Plugin Spec, and the bundled implementation is defined by the Default Control Plugin Implementation Spec.

Control is an anti-fragility mechanism. It protects a Nacos node by rejecting or monitoring requests when access to a control point exceeds configured rules. Control plugins must not change resource semantics; they only decide whether the current connection or request may continue.

HTTP and gRPC TPS control hooks are connected through the shared request filtering model defined by the Request Filtering And Runtime Context Spec.

Concepts

Concept	Meaning
Control point	A named runtime resource that can be measured and limited.
Connection control	Admission control for long connections or long polling connections.
TPS control	Admission control for request frequency at a named API operation point.
Rule storage	Storage that persists rule text for local or external distribution.
Rule parser	Parser that converts stored rule text into runtime rule objects.
Barrier	Runtime TPS counter and decision component for a point.

Connection and TPS control are independent. A deployment may provide both managers, only one manager, or no manager. A missing manager is treated as no-limit for that dimension.

SPI

Control plugins implement ControlManagerBuilder.

Method	Requirement
getName()	Stable plugin name.
buildConnectionControlManager()	Build connection control manager.
buildTpsControlManager()	Build TPS control manager.

External rule storage plugins implement ExternalRuleStorageBuilder and are selected independently through control configuration.

The plugin is exposed to the core plugin manager as type control.

Managers

ConnectionControlManager owns connection rules and returns ConnectionCheckResponse for connection admission. It may load ConnectionMetricsCollector implementations to report connection metrics.

Required connection manager behavior:

Method	Requirement
applyConnectionLimitRule(rule)	Apply the latest connection rule.
check(request)	Return pass or reject for a connection admission request.
buildConnectionControlRuleParser()	Optionally override the rule text parser.

TpsControlManager owns TPS points, TPS rules, and barriers. It returns TpsCheckResponse for TPS admission.

Required TPS manager behavior:

Method	Requirement
registerTpsPoint(pointName)	Register a control point during startup or route scan.
applyTpsRule(pointName, rule)	Apply or remove the rule for a point.
check(request)	Return pass or reject for a TPS request.
buildTpsControlRuleParser()	Optionally override the rule text parser.
buildTpsBarrierCreator()	Optionally override time-window and counter behavior.

Rule Model

ConnectionControlRule contains:

Field	Meaning
countLimit	Maximum total connection count. A value below 0 means no limit.
monitorIpList	IP addresses whose connection behavior should be logged in detail.

TpsControlRule contains:

Field	Meaning
pointName	Control point name.
pointRule	Rule detail for the control point.

RuleDetail contains:

Field	Meaning
ruleName	Rule identifier. A point may have multiple rule names in custom plugins.
maxCount	Maximum allowed count in the period. A value below 0 means no limit.
period	Counting period. The built-in default is seconds.
monitorType	monitor for observation only, or intercept for rejection.

Rule Storage

Rules may come from local disk storage or an external rule storage plugin. Local rules are always available as the safe baseline. External rule storage must fail closed only when the selected control plugin explicitly requires it.

Rule reloads are published through control rule change events and applied by the active managers. Local event dispatch follows the Event Dispatch And NotifyCenter Spec. Control metrics and denied observations follow the Observability Hooks Spec.

External rule storage is selected by:

nacos.plugin.control.rule.external.storage=${controlPluginName}

The local rule storage base directory is selected by:

nacos.plugin.control.rule.local.basedir=${expectedDir}

Custom control plugins may support non-JSON rule text by overriding the rule parser methods. Custom TPS plugins may support sliding windows or other counter algorithms by overriding the barrier creator.

Selection And State

The selected manager implementation is named by:

nacos.plugin.control.manager.type=${controlPluginName}

The selected control plugin must also respect unified plugin state for control:{pluginName} when integrated through the core plugin manager.

Point names are part of the public control contract. New @TpsControl points must use stable names, document the protected operation, and preserve the name when HTTP and gRPC endpoints represent the same semantic operation.

Degradation

Control plugins affect request admission. If plugin construction fails, Nacos must fall back to no-limit managers and log the failure unless the deployment explicitly configures a fail-fast policy.

Runtime plugin exceptions must not corrupt request state. For monitoring-only rules, failures should be logged and skipped. For intercepting rules, the selected plugin owns whether a failure means pass, reject, or fail fast, and that behavior must be documented by the implementation spec.