tls: document Prefer mode plaintext behavior

src/NATS.Client.Core/NatsOpts.cs

@@ -72,6 +72,16 @@ public sealed record NatsOpts
 
     public NatsAuthOpts AuthOpts { get; init; } = new();
 
+    /// <summary>
+    /// TLS options for the connection.
+    /// </summary>
+    /// <remarks>
+    /// By default the client attempts a TLS upgrade when the server advertises TLS support.
+    /// If you don't want TLS (e.g. behind a TLS-terminating proxy), set
+    /// <see cref="NatsTlsOpts.Mode"/> to <see cref="TlsMode.Disable"/>.
+    /// </remarks>
+    /// <seealso cref="NatsTlsOpts.Mode"/>
+    /// <seealso cref="TlsMode"/>
     public NatsTlsOpts TlsOpts { get; init; } = new();
 
     public NatsWebSocketOpts WebSocketOpts { get; init; } = new();

src/NATS.Client.Core/NatsTlsOpts.cs

@@ -14,14 +14,34 @@ namespace NATS.Client.Core;
 public enum TlsMode
 {
     /// <summary>
-    /// For connections that use the "nats://" scheme and don't supply Client or CA Certificates - same as <c>Prefer</c>
-    /// For connections that use the "tls://" scheme or supply Client or CA Certificates - same as <c>Require</c>
+    /// For connections that use the "nats://" scheme and don't supply Client or CA Certificates - same as <see cref="Prefer"/>.
+    /// For connections that use the "tls://" scheme or supply Client or CA Certificates - same as <see cref="Require"/>.
     /// </summary>
+    /// <remarks>
+    /// When this resolves to <see cref="Prefer"/>, TLS is opportunistic: the connection
+    /// may remain plaintext depending on the server's INFO response.
+    /// Use the <c>tls://</c> scheme or set <see cref="Require"/> explicitly when TLS is required.
+    /// </remarks>
     Auto,
 
     /// <summary>
-    /// if the Server supports TLS, then use it, otherwise use plain-text.
+    /// If the server supports TLS, then use it; otherwise, use plain-text.
     /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This is an opportunistic TLS mode. The TLS decision is based on the server's
+    /// INFO message, which arrives over plaintext before any encryption is established.
+    /// On an untrusted network the connection may remain plaintext.
+    /// </para>
+    /// <para>
+    /// When connecting directly, this mode upgrades to TLS if the server supports it.
+    /// Behind a TLS-terminating proxy, use <see cref="TlsMode.Disable"/> instead,
+    /// as the client may attempt a TLS upgrade that the nats-server cannot complete.
+    /// </para>
+    /// <para>
+    /// If TLS is required, use the <c>tls://</c> scheme or set <see cref="TlsMode.Require"/> explicitly.
+    /// </para>
+    /// </remarks>
     Prefer,
 
     /// <summary>
@@ -99,7 +119,22 @@ public sealed record NatsTlsOpts
     /// <summary>When true, skip remote certificate verification and accept any server certificate</summary>
     public bool InsecureSkipVerify { get; init; }
 
-    /// <summary>TLS mode to use during connection</summary>
+    /// <summary>
+    /// TLS mode to use during connection.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Defaults to <see cref="TlsMode.Auto"/>, which resolves to <see cref="TlsMode.Prefer"/>
+    /// for <c>nats://</c> connections without certificates. In this mode the client will
+    /// attempt a TLS upgrade when the server advertises TLS support. This differs from most
+    /// other NATS clients, which do not upgrade unless explicitly configured.
+    /// </para>
+    /// <para>
+    /// Behind a TLS-terminating proxy, use <see cref="TlsMode.Disable"/> to prevent the
+    /// client from attempting a TLS upgrade that the nats-server cannot complete.
+    /// Use the <c>tls://</c> scheme or <see cref="TlsMode.Require"/> when TLS is required.
+    /// </para>
+    /// </remarks>
     public TlsMode Mode { get; init; }
 
     internal bool HasTlsCerts

tests/NATS.Client.Core2.Tests/NATS.Client.Core2.Tests.csproj

@@ -16,6 +16,7 @@
 
     <ItemGroup>
         <PackageReference Include="FluentAssertions" Version="[7,8)" />
+        <PackageReference Include="Synadia.Orbit.Testing.GoHarness" Version="1.0.0-preview.1" />
         <PackageReference Include="ProcessX" Version="1.5.6" />
         <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
         <PackageReference Include="xunit.v3" Version="1.0.1" />