docs(http): document Gun pool behavior

DEVLOG.md

@@ -0,0 +1,12 @@
+# Development Log
+
+## Gun pool validation
+
+- The previous unique origin registry forced concurrent HTTP/1 requests onto one connection.
+- Pool identity omitted proxy routes and credentials, allowing incompatible routes to reuse a connection.
+- Gun 2.2 CONNECT requests require their tunnel stream reference on subsequent requests; Tesla's bundled Gun adapter does not preserve it.
+- CONNECT and SOCKS5 setup returned before the destination tunnel was ready and did not pass authentication credentials.
+- The existing global `max_connections` limit and idle reclaimer bound HTTP/1 sibling and many-host connection growth.
+- SOCKS4 is not supported by Gun 2.2 and is now rejected explicitly by the Gun adapter.
+- Gun reports a stale stream error to the process that calls `cancel/2`; pool workers must consume that reply so one HTTP/2 cancellation cannot terminate other multiplexed requests.
+- Streamed uploads must be registered before body enumeration and cancelled if enumeration exits, throws, or raises, otherwise a partial HTTP/1 request can remain reusable.

changelog.d/gun-pool-rework.fix

@@ -0,0 +1 @@
+Fixed Gun HTTP/1 concurrency, authenticated proxy handling, tunnel requests, and streamed connection cleanup.

docs/configuration/cheatsheet.md

@@ -573,7 +573,8 @@ Settings for HTTP connection pool.
 
 * `:connection_acquisition_wait` - Timeout to acquire a connection from pool.The total max time is this value multiplied by the number of retries.
 * `connection_acquisition_retries` - Number of attempts to acquire the connection from the pool if it is overloaded. Each attempt is timed `:connection_acquisition_wait` apart.
-* `:max_connections` - Maximum number of connections in the pool.
+* `:max_connections` - Maximum total number of connections in the pool. HTTP/1 origins may use multiple connections within this limit, while HTTP/2 connections are multiplexed.
+* `:max_idle_time` - Time before an unused connection is closed.
 * `:connect_timeout` - Timeout to connect to the host.
 * `:reclaim_multiplier` - Multiplied by `:max_connections` this will be the maximum number of idle connections that will be reclaimed in case the pool is overloaded.
 

docs/configuration/howto_proxy.md

@@ -10,3 +10,5 @@ The other way to do it, for example, with Tor you would most likely add somethin
 ```
 config :pleroma, :http, proxy_url: {:socks5, :localhost, 9050}
 ```
+
+The Gun HTTP adapter supports SOCKS5. SOCKS4 proxies require another HTTP adapter.