Summary

This PR introduces the traffic-label plugin, which assigns configurable labels to requests based on weighted random distribution rules.

Description

The traffic-label plugin selects a label from a configured set of weighted labels and writes it to a request header or APISIX variable. Multiple rules can be configured, each with an optional match condition using resty.expr expressions. The first matching rule is applied; if no rule matches, the plugin is a no-op.

Use cases:

• A/B testing by tagging requests and routing based on the label
• Canary deployments with weighted traffic splitting at the label level
• Request classification for observability and analytics

Key features

• Weighted random label selection per rule
• Optional resty.expr-based match conditions
• Writes selected label to a request header or APISIX variable
• First-match semantics across multiple rules

Example

The following example assigns the label gray to 10% of requests and stable to 90%, writing the result to the X-Traffic-Label header:

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $admin_key" -X PUT -d '{
  "uri": "/api/*",
  "plugins": {
    "traffic-label": {
      "rules": [
        {
          "weighted_labels": [
            { "label": "gray",   "weight": 10 },
            { "label": "stable", "weight": 90 }
          ],
          "header": "X-Traffic-Label"
        }
      ]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": { "127.0.0.1:1980": 1 }
  }
}'

Downstream services can then read X-Traffic-Label to apply canary logic.

Files changed

• apisix/plugins/traffic-label.lua — plugin implementation
• t/plugin/traffic-label.t — basic test cases
• t/plugin/traffic-label2.t — extended test cases
• docs/en/latest/plugins/traffic-label.md — English documentation
• docs/zh/latest/plugins/traffic-label.md — Chinese documentation
• apisix/cli/config.lua — register plugin in default list
• docs/en/latest/config.json / docs/zh/latest/config.json — add to sidebar