Fix inverted async initial-connect retry docs

Commit 994554e rewrote the initial_connect_retry=async docs to claim
that transport, auth, upgrade and capability failures are all retried
indefinitely and never surfaced. That over-generalized the transport
retry-forever rule (Invariant B) onto endpoint-policy failures and
inverted a deliberately engineered, test-proven contract.

endpointPolicyFailureIsTerminal() returns ORPHAN || !hasEverConnected,
so on a foreground sender's initial connect an auth, upgrade or
durable-ack capability rejection is terminal: connectLoop latches it
via recordFatal and dispatches it to the async SenderErrorHandler (a
close() rethrow in ASYNC, a throw from build() in SYNC/OFF). Only
transport failures, and endpoint-policy failures once the wire has
been up at least once, retry forever. InitialConnectAsyncTest proves
both halves: testAsyncAuthFailureSurfacesTerminal the terminal path,
testAsyncNoServerRetriesForeverNoTerminal the transport path.

The wrong wording risked an operator not wiring an error_handler and
then silently buffering into store-and-forward on an auth
misconfiguration. Restore the carve-out in all four docstrings the
commit inverted: the Sender.InitialConnectMode.ASYNC javadoc, the
CursorWebSocketSendLoop class-doc and attemptInitialConnect() javadoc,
the QwpWebSocketSender ASYNC-case comment, and the
InitialConnectAsyncTest class javadoc. Documentation only; no runtime
behavior changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: glasstiger

core/src/main/java/io/questdb/client/Sender.java

@@ -795,9 +795,16 @@ default Sender uuidColumn(CharSequence name, long lo, long hi) {
      *       unconnected sender; the I/O thread runs the same retry loop in
      *       the background. The user thread can call {@code at()} /
      *       {@code flush()} immediately; rows accumulate in the cursor SF
-     *       engine until the wire is up. Transport, auth, upgrade and
-     *       capability failures are retried indefinitely in the background;
-     *       none is surfaced to producer calls or the async error inbox.</li>
+     *       engine until the wire is up. Transport failures (unreachable or
+     *       dropped server) retry indefinitely and are never surfaced -- the
+     *       buffered rows are safe in SF and the server may still appear. A
+     *       terminal auth, upgrade or capability rejection on the initial
+     *       connect (before the wire has ever come up) has no caller left to
+     *       throw at, so it is delivered to the async error inbox as a
+     *       {@link io.questdb.client.SenderError}; wire {@code error_handler=...}
+     *       to observe it. Once the wire has come up even once, SF owns the
+     *       buffered data and the same rejections (e.g. a credential rotation)
+     *       become transients retried indefinitely.</li>
      * </ul>
      * <p>
      * Default resolution when the caller does not pick a value:

core/src/main/java/io/questdb/client/cutlass/qwp/client/QwpWebSocketSender.java

@@ -3398,10 +3398,12 @@ private void ensureConnected() {
                 // Encoder stays at its default (V1 -- the only supported wire
                 // version today). Frames written before the first successful
                 // connect commit to V1 because cursor segments are immutable;
-                // a future version bump must account for that. Auth, upgrade,
-                // capability and transport failures all retry indefinitely on
-                // the I/O thread (Invariant B); none is surfaced here or later
-                // to the producer.
+                // a future version bump must account for that. Transport
+                // failures retry indefinitely on the I/O thread (Invariant B).
+                // But a terminal auth, upgrade or capability rejection on this
+                // initial connect -- before the wire is ever up -- is surfaced
+                // to the async SenderErrorHandler and latched for a close()
+                // rethrow, not retried.
                 client = null;
                 break;
             case OFF:

core/src/main/java/io/questdb/client/cutlass/qwp/client/sf/cursor/CursorWebSocketSendLoop.java

@@ -68,11 +68,13 @@
  *       can trim fully-acked segments.</li>
  *   <li>On wire failure, runs the configured reconnect policy: capped
  *       exponential backoff with jitter, retried indefinitely (Invariant B --
- *       a store-and-forward drainer never gives up on a wall-clock budget),
- *       with endpoint-policy failures terminal only for an orphan drainer. A
- *       foreground sender keeps retrying from asynchronous startup onward so
- *       credential and rolling-capability changes remain contained by
- *       store-and-forward. On reconnect success, repositions the cursor at
+ *       a store-and-forward drainer never gives up on a wall-clock budget).
+ *       Once a foreground sender has connected even once, endpoint-policy
+ *       failures (auth, upgrade, durable-ack capability) become transients it
+ *       keeps retrying, so credential and rolling-capability changes stay
+ *       contained by store-and-forward; they are terminal only for an orphan
+ *       drainer or on a foreground sender's initial connect (before the wire
+ *       has ever come up). On reconnect success, repositions the cursor at
  *       {@code ackedFsn+1} and replays.</li>
  * </ol>
  * No locks on the steady-state path. The producer thread (user) writes
@@ -1505,9 +1507,11 @@ private void applyDurableAck() {
      * Drives the very first connect attempt on the I/O thread, used in the
      * async-initial-connect mode (constructed with {@code client == null}).
      * Reuses the same retry+backoff machinery as {@link #fail(Throwable)}.
-     * Transport, authentication, upgrade and capability failures are all
-     * retried indefinitely here (Invariant B); none is surfaced to the
-     * foreground producer.
+     * Transport failures retry indefinitely here (Invariant B). But this path
+     * runs with {@code !hasEverConnected}, so an auth, upgrade or capability
+     * rejection is terminal (see {@link #endpointPolicyFailureIsTerminal()}):
+     * it is dispatched to the async {@code SenderErrorHandler} and latched for
+     * a {@code close()} rethrow, rather than retried.
      */
     private void attemptInitialConnect() {
         connectLoop(new LineSenderException(

core/src/test/java/io/questdb/client/test/cutlass/qwp/client/InitialConnectAsyncTest.java

@@ -49,11 +49,13 @@
 /**
  * Behavior of {@code initial_connect_retry=async}: the producer-thread
  * {@code Sender.fromConfig} must return immediately even when no server
- * is reachable; the I/O thread retries connect in the background. Plain
- * failures are retried indefinitely (Invariant B: no wall-clock budget
- * give-up), including authentication, upgrade and durable-ack capability
- * failures. Those endpoint states stay inside the I/O thread and never stop
- * the producer.
+ * is reachable; the I/O thread retries connect in the background. Transport
+ * failures (unreachable or dropped server) are retried indefinitely
+ * (Invariant B: no wall-clock budget give-up) and never stop the producer.
+ * But the initial connect has never reached the server, so an endpoint-policy
+ * rejection there -- authentication, upgrade or durable-ack capability -- is
+ * terminal: with no caller thread left to throw at, it is delivered to the
+ * {@code SenderErrorHandler} instead of buffering forever.
  */
 public class InitialConnectAsyncTest {