fix(conn-mgr): add :max-total, correct misleading :threads docs (#633) (#663)

The :threads option for make-reusable-conn-manager and
make-reusable-async-conn-manager never controlled a thread count; it is
passed straight to PoolingHttpClientConnectionManager.setMaxTotal, i.e. the
pool's maximum total connections. The docstring described it as a thread
count, which is misleading.

Add :max-total as an accurately-named option and keep :threads working as a
deprecated alias (:max-total wins if both are supplied). Document the
distinction. Fixes #633.

Co-authored-by: Lee Hinman <dakrone@users.noreply.github.com>

Author: jsavyasachi

src/clj_http/conn_mgr.clj

@@ -238,8 +238,11 @@
 
   :timeout - Time that connections are left open before automatically closing
     default: 5
-  :threads - Maximum number of threads that will be used for connecting
+  :max-total - Maximum number of total connections kept in the pool
     default: 4
+  :threads - Deprecated alias for :max-total. Despite the name, this option
+    has never controlled a number of threads; it sets the pool's maximum
+    total connections. Prefer :max-total. If both are given, :max-total wins.
   :default-per-route - Maximum number of simultaneous connections per host
     default: 2
   :insecure? - Boolean flag to specify allowing insecure HTTPS connections
@@ -264,14 +267,14 @@
   will be used."
   [opts]
   (let [timeout (or (:timeout opts) 5)
-        threads (or (:threads opts) 4)
+        max-total (or (:max-total opts) (:threads opts) 4)
         default-per-route (:default-per-route opts)
         insecure? (opt opts :insecure)
-        leftovers (dissoc opts :timeout :threads :insecure? :insecure)
+        leftovers (dissoc opts :timeout :threads :max-total :insecure? :insecure)
         conn-man (make-reusable-conn-manager* (merge {:timeout timeout
                                                       :insecure? insecure?}
                                                      leftovers))]
-    (.setMaxTotal conn-man threads)
+    (.setMaxTotal conn-man max-total)
     (when default-per-route
       (.setDefaultMaxPerRoute conn-man default-per-route))
     conn-man))
@@ -327,13 +330,13 @@
   will be used."
   [opts]
   (let [timeout (or (:timeout opts) 5)
-        threads (or (:threads opts) 4)
+        max-total (or (:max-total opts) (:threads opts) 4)
         default-per-route (:default-per-route opts)
         insecure? (opt opts :insecure)
-        leftovers (dissoc opts :timeout :threads :insecure? :insecure)
+        leftovers (dissoc opts :timeout :threads :max-total :insecure? :insecure)
         conn-man (make-reusable-async-conn-manager*
                   (merge {:timeout timeout :insecure? insecure?} leftovers))]
-    (.setMaxTotal conn-man threads)
+    (.setMaxTotal conn-man max-total)
     (when default-per-route
       (.setDefaultMaxPerRoute conn-man default-per-route))
     conn-man))

test/clj_http/test/conn_mgr_test.clj

@@ -150,3 +150,17 @@
     (is (false? (conn-mgr/reusable? async)))
     (is (true? (conn-mgr/reusable? async-reusable)))
     (is (true? (conn-mgr/reusable? async-reuseable)))))
+
+(deftest max-total-and-threads-alias
+  (testing ":threads still sets the pool's max total connections (back-compat)"
+    (let [cm (conn-mgr/make-reusable-conn-manager {:threads 7})]
+      (is (= 7 (.getMaxTotal cm)))))
+  (testing ":max-total sets the pool's max total connections"
+    (let [cm (conn-mgr/make-reusable-conn-manager {:max-total 9})]
+      (is (= 9 (.getMaxTotal cm)))))
+  (testing ":max-total takes precedence when both are given"
+    (let [cm (conn-mgr/make-reusable-conn-manager {:max-total 9 :threads 3})]
+      (is (= 9 (.getMaxTotal cm)))))
+  (testing "default max total is 4"
+    (let [cm (conn-mgr/make-reusable-conn-manager {})]
+      (is (= 4 (.getMaxTotal cm))))))