feat(cli): align PROXY Protocol configuration with node_listen and ssl.listen, add IPv6 support

[twellck]

Description

This pull request aligns the configuration and handling of PROXY Protocol listen ports with the structure used for node_listen and ssl.listen. It adds support for specifying multiple ports and IP addresses (including IPv6), introduces schema validation improvements, ensures backward compatibility with legacy options, and updates documentation.

Key Changes:

Configuration and Schema Improvements:

• Added support for proxy_protocol.listen_http and proxy_protocol.listen_https as new configuration options.
  • These options allow specifying multiple ports and IP addresses (including IPv6) for PROXY Protocol.
  • New schema validation supports integers, objects, and arrays for port and IP address definitions.
• Deprecated proxy_protocol.listen_http_port and proxy_protocol.listen_https_port fields for PROXY Protocol while ensuring backward compatibility.
• Updated config.yaml.example to document the new structure and usage patterns for PROXY Protocol listen options.

Backward Compatibility & Warnings:

• CLI logic detects the use of deprecated proxy_protocol.listen_http_port and proxy_protocol.listen_https_port fields, issuing warnings, and internally treats them the same as the new configuration (only when legacy fields are present).

Template, Runtime, and IPv6 Support:

• Updated the Nginx configuration template (ngx_tpl.lua) to use listen_http and listen_https fields.
• Ensures IPv6 support for PROXY Protocol by dynamically generating additional Nginx listen directives for IPv6 addresses.

Documentation Updates:

• Example and inline documentation updated to illustrate:
  • Migration from listen_http_port and listen_https_port to listen_http/listen_https.
  • How to specify multiple ports and use specific IPv4/IPv6 bindings.

Testing Enhancements:

• Added test scenarios for new and legacy configurations, including:
  • Tests for backward compatibility with proxy_protocol.listen_http_port and proxy_protocol.listen_https_port.
  • Validations for the new listen_http and listen_https formats, IPv4/IPv6 combinations, and support for QUIC/HTTP3.
  • Additional tests for unusual inputs, such as unformatted or malformed IPv6 literals.

Which issue(s) this PR fixes:

Fixes #12828

Checklist

• I have explained the need for this PR and the problem it solves.
• I have explained the changes or the new features added to this PR.
• I have added tests corresponding to this change.
• I have updated the documentation to reflect this change.
• I have verified that this change is backward compatible (If not, please discuss on the APISIX mailing list first).

---

Notes for Reviewers

• This PR focuses on improving user flexibility and extending IPv6 support for PROXY Protocol configurations.
• Provides backward-compatible changes to preserve legacy functionality while guiding users toward the new configuration structure.
• Suggested areas for additional review:
  • Schema changes and edge case validation.
  • Adequacy of tests, particularly for IPv6 bindings and legacy support.

---

Note: AI helped format this Pull Request.

[Baoyuantop]

Hi @twellck, For the original problem, we only needed to add IPv6 listening to the template; the current modifications are too complex.

{% if proxy_protocol and proxy_protocol.listen_http_port then %}
listen {* proxy_protocol.listen_http_port *} default_server proxy_protocol;
{% if enable_ipv6 then %}
listen [::]:{* proxy_protocol.listen_http_port *} default_server proxy_protocol;
{% end %}
{% end %}

[twellck]

Hi @Baoyuantop,

Thank you for the comment!

While the proposed approach would indeed address the immediate issue, I believe it treats the symptom rather than the root cause. My current implementation attempts to address the underlying problem by introducing some standardisation to how listeners are managed going forward.

Adding IPv6 listening directly to the template would further fragment how listeners (node_listen, proxy_protocol.listen_http_port, control/admin/prometheus, etc.) are managed in the APISIX and Nginx configuration. Each of these currently relies on slightly different approaches for defining listener behavior. This fragmentation not only increases maintenance complexity but also limits the ability to provide feature parity across all listening definitions.

My proposed solution is fully backward-compatible, based on regression testing, and builds on the established patterns for node_listen and ssl.listen in APISIX (reworked into reusable functions). By leveraging these existing structures, my hope is to reduce ongoing maintenance efforts while making future listener functionality easier to extend.

---

For now, this PR focuses specifically on standardising proxy_protocol to keep the changes targeted and manageable. However, I’d be happy to explore extending this standardisation approach to other listeners like admin, control, and prometheus in the Nginx configuration in the future, if that’s something the team sees value in.

I understand that this PR addresses more than the specific issue, but I believe it’s worth considering how we could make Nginx configuration more standardised and maintainable for both developers and deployers of APISIX over time.

[Baoyuantop]

Hi @twellck, the scope of changes in this PR far exceeds the requirements outlined in the issue. To maintain code base simplicity and maintainability, we recommend:

1. Modify only ngx_tpl.lua to add IPv6 listening support (approximately 10 lines of code).
2. If broader refactoring is needed, we suggest opening a separate issue to discuss technical approaches.