Say what the disconnect contract covers

The contract in ssh.h claimed more than the code does. A CHANNEL_EOF
already received outranks the drain, so both stream reads report WS_EOF
with data still buffered, and wolfSSH_accept()/wolfSSH_connect() never
look at the flag at all. Both fixes belong with the channel EOF work in
#1195; until then the header says what is really gated.

Issue: F-8837

Author: ejohnstown

wolfssh/internal.h

@@ -1102,11 +1102,12 @@ struct WOLFSSH {
 #endif
     byte connReset;
     byte isClosed;
-    /* Set when a DISCONNECT is sent or received. Gates every public send
-     * call, so nothing more goes out. Reads still hand back what arrived
+    /* Set when a DISCONNECT is sent or received. Gates the public send
+     * calls, so nothing more goes out. Reads still hand back what arrived
      * before the disconnect; the head-of-list reads report it once their
-     * buffer runs dry. wolfSSH_worker() is not gated, the shutdown paths
-     * pump it. */
+     * buffer runs dry, unless a CHANNEL_EOF arrived first. wolfSSH_worker(),
+     * wolfSSH_accept() and wolfSSH_connect() are not gated; the shutdown
+     * paths pump the worker. */
     byte disconnected;
     /* Set once SendDisconnect() has bundled our own DISCONNECT into the
      * output buffer, so a short send can still be flushed. The flag above

wolfssh/ssh.h

@@ -559,11 +559,14 @@ WOLFSSH_API int wolfSSH_accept(WOLFSSH* ssh);
 WOLFSSH_API int wolfSSH_connect(WOLFSSH* ssh);
 WOLFSSH_API int wolfSSH_shutdown(WOLFSSH* ssh);
 /* A disconnect, sent or received, ends the session. Nothing more goes out:
- * every send call in this header, above this comment and below it, reports
- * WS_DISCONNECT from then on. Reads are not gated, so channel data that
+ * wolfSSH_shutdown() above this comment, and every send call below it,
+ * report WS_DISCONNECT from then on. wolfSSH_accept() and
+ * wolfSSH_connect() are not gated; do not drive the handshake after a
+ * disconnect. Reads are not gated either, so channel data that
  * arrived before the disconnect can still be drained; wolfSSH_stream_read()
  * and wolfSSH_stream_peek() report WS_DISCONNECT once their buffer runs
- * dry. RFC 4253 section 11.1. */
+ * dry. A CHANNEL_EOF already received outranks that drain: both report
+ * WS_EOF with data possibly still buffered. RFC 4253 section 11.1. */
 WOLFSSH_API int wolfSSH_stream_peek(WOLFSSH* ssh, byte* buf, word32 bufSz);
 WOLFSSH_API int wolfSSH_stream_read(WOLFSSH* ssh, byte* buf, word32 bufSz);
 WOLFSSH_API int wolfSSH_stream_send(WOLFSSH* ssh, byte* buf, word32 bufSz);