260208 add ppv2 auto mode

.github/workflows/run_test_case.yaml

@@ -33,4 +33,3 @@ jobs:
             make eunit
             make ct
             make cover
-

.gitignore

@@ -33,3 +33,4 @@ rebar3.crashdump
 .rebar3/
 rebar.lock
 TEST-*.xml
+.agent

README.md

@@ -89,12 +89,26 @@ Option:
                     | {access_rules, [esockd_access:rule()]}
                     | {shutdown, brutal_kill | infinity | pos_integer()}
                     | tune_buffer | {tune_buffer, boolean()}
-                    | proxy_protocol | {proxy_protocol, boolean()}
+                    | proxy_protocol | {proxy_protocol, boolean() | auto}
                     | {proxy_protocol_timeout, timeout()}
                     | {ssl_options, [ssl:ssl_option()]}
                     | {udp_options, [gen_udp:option()]}
                     | {dtls_options, [gen_udp:option() | ssl:ssl_option()]}).
 
+Proxy protocol modes:
+
+    {proxy_protocol, true}   %% strict: every connection must send PROXY header
+    {proxy_protocol, false}  %% disabled
+    {proxy_protocol, auto}   %% conditional PPv2 parsing:
+                             %% - `esockd:open/3` (gen_tcp): only with `{packet, raw}` and without `ssl_options`
+                             %% - `esockd:open_tcpsocket/3`: supported
+
+Caution for `proxy_protocol = auto`:
+
+1. `wait/1` may return either `{ok, Socket}` or `{ok, Socket, Prefetched}` when `auto` is enabled.
+2. If prefetched bytes are returned, the application must process/prepend them before continuing normal socket reads.
+3. Do not use this mode when first application payload can be fragmented and start with a PPv2-signature prefix (for example `<<"\r\n">>`). In this case esockd waits for disambiguation and fail-closes the connection on timeout/close while matching the signature prefix.
+
 MFArgs:
 
     -type(mfargs() :: atom() | {atom(), atom()} | {module(), atom(), [term()]}).
@@ -199,4 +213,3 @@ Apache License Version 2.0
 ## Author
 
 EMQX Team.
-

changelog.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 5.17.0 - 2026-02
+
+### Added
+- Added `proxy_protocol = auto` support for both `gen_tcp` and socket listeners.
+- Added conditional `wait/1` prefetched return support for auto-upgrade flows.
+
+### Changed
+- Enforced `proxy_protocol = auto` only when `{packet, raw}` is used.
+- Made partial PROXY protocol v2 signature upgrade failures fail fast with meaningful reasons (`proxy_proto_timeout`, `proxy_proto_close`) returned to applications.
+
+

rebar.config

@@ -41,7 +41,8 @@
              "examples/simple",
              "examples/tls",
              "examples/tcp_window",
-             "examples/udp"
+             "examples/udp",
+             "test/integration/ppv2_compose"
             ]}
         ]}
     ]}.

src/esockd.erl

@@ -111,7 +111,7 @@
                 | {access_rules, [esockd_access:rule()]}
                 | {shutdown, brutal_kill | infinity | pos_integer()}
                 | tune_buffer | {tune_buffer, boolean()}
-                | proxy_protocol | {proxy_protocol, boolean()}
+                | proxy_protocol | {proxy_protocol, boolean() | auto}
                 | {proxy_protocol_timeout, timeout()}
                 | {ssl_options, ssl_options()}
                 | {tcp_options, [gen_tcp:listen_option()]}
@@ -426,6 +426,8 @@ parse_opt([proxy_protocol|Opts], Acc) ->
     parse_opt(Opts, [{proxy_protocol, true}|Acc]);
 parse_opt([{proxy_protocol, I}|Opts], Acc) when is_boolean(I) ->
     parse_opt(Opts, [{proxy_protocol, I}|Acc]);
+parse_opt([{proxy_protocol, auto}|Opts], Acc) ->
+    parse_opt(Opts, [{proxy_protocol, auto}|Acc]);
 parse_opt([{proxy_protocol_timeout, Timeout}|Opts], Acc) when is_integer(Timeout) ->
     parse_opt(Opts, [{proxy_protocol_timeout, Timeout}|Acc]);
 parse_opt([{ssl_options, L}|Opts], Acc) when is_list(L) ->