[Proposal] Query parameter rewriting in proxy-rewrite

[ruanweihong-aaa]

I'd like to discuss the configuration API for query parameter rewriting in proxy-rewrite, related to #11237.

The proposed operations are:

• remove: remove all values for a parameter name.
• rename: rename a parameter while preserving its values.
• replace: replace all values only when the parameter exists.
• add: add a parameter only when it is absent.
• append: append a value, creating the parameter if it is absent.

Before finalizing the implementation, I'd like feedback on the configuration structure and naming.

Would grouping these operations under args be appropriate, consistent with how header operations are grouped under headers?

For example, one possible configuration would be:

{
  "args": {
    "remove": ["token"],
    "rename": {"old": "new"},
    "replace": {"a": "11"},
    "add": {"b": "22"},
    "append": {"c": "33"}
  }
}

Alternatively, would query or querystring be a clearer name? The example above is a proposed API for discussion, rather than the finalized configuration format.

The current implementation executes the operations in the following order, regardless of the order of fields in the configuration:

remove → rename → replace → add → append

I'd also appreciate feedback on whether this execution order is appropriate.

The initial implementation supports literal values only, without dynamic templates.

Feedback on the naming, configuration structure, and operation semantics would be appreciated.

[membphis]

Grouping the operations under args looks reasonable. My main suggestion is to reuse the existing headers operation semantics:

• add: append the configured values while preserving existing values; create the parameter if it is absent.
• set: replace all existing values with the configured values; create the parameter if it is absent.
• remove: remove all values for the parameter name.

Both add and set should accept scalar values and arrays. For example:

{
  "args": {
    "add": {"tag": ["b", "c"]},
    "set": {"page": "1"},
    "remove": ["token"]
  }
}

Given ?tag=a&page=2&page=3&token=tmp, the upstream should receive the equivalent of ?tag=a&tag=b&tag=c&page=1. This example illustrates the parameter values, without requiring a particular ordering between different parameter names. Setting an array should also replace the entire existing value list: setting k to ["3", "4"] turns k=1&k=2 into k=3&k=4.

Repeated query parameter names are valid and need to be preserved. Internally, the implementation should handle both scalar and multi-value representations, including appending to either without losing existing values or creating nested arrays. On the wire, multiple values should be emitted as repeated key-value pairs, preserving their order for the same key. Backend platforms may expose these as arrays or retain the first or last value, depending on their parser. APISIX should preserve the repeated pairs; a scalar set provides an explicit way to send a single replacement value.

With these semantics, a separate append operation is unnecessary because add already covers it. The proposed conditional replace operation should not take the place of set. I would start with add, set, and remove, and consider rename or conditional replacement separately if concrete use cases justify them.

The execution order should be explicit and deterministic. One detail to clarify first: the current headers implementation executes add -> set -> remove, while the documentation says add -> remove -> set. We should resolve that discrepancy and establish a consistent order before applying it to args.