Bump Suave from 2.6.2 to 3.4.6 (#1272)

Migrate the fsdocs watch server to Suave 3's Task-based socket API:
the websocket handler and reload broadcast now use ValueTask/Result,
the removed Suave.Logging module is dropped, and the server task from
startWebServerAsync is already hot so it no longer needs Async.Start.

While migrating, fix a crash in watch mode: clients that disconnect
without a close handshake stayed registered, and broadcasting to such
a dead socket throws ObjectDisposedException in Suave 3, killing the
whole watch process. Clients are now deregistered whenever their
connection ends, and the broadcast tolerates stale sockets.

Also in watch mode, the logo now links to the locally hosted site
root instead of the production URL (even when <FsDocsLogoLink> is
set), and the console no longer logs websocket connection chatter on
every page reload. Release builds are unaffected.

Bump Fun.Build from 1.0.4 to 1.1.18 and make build.fsx directly
executable via a dotnet fsi shebang.

Release notes: 22.2.0.

Author: nojaf

Directory.Packages.props

@@ -15,7 +15,7 @@
     <PackageVersion Include="Microsoft.Build.Tasks.Core" Version="" PrivateAssets="all" />
     <PackageVersion Include="Ionide.ProjInfo" Version="0.74.2" />
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
-    <PackageVersion Include="Suave" Version="2.6.2" />
+    <PackageVersion Include="Suave" Version="3.4.6" />
     <PackageVersion Include="System.Memory" Version="4.6.3" />
     <PackageVersion Include="System.Text.Json" Version="10.0.8" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.7.0" />

RELEASE_NOTES.md

@@ -1,6 +1,11 @@
 # Changelog
 
-## [Unreleased]
+## [22.2.0] - 2026-08-31
+
+### Changed
+* Bump `Suave` from 2.6.2 to 3.4.6. The `fsdocs watch` websocket handling was migrated to Suave 3's `Task`-based socket API, the removed `Suave.Logging` usage was dropped, and clients that disconnect without a close handshake are now deregistered so a live-reload broadcast can no longer crash the watch server with an `ObjectDisposedException`.
+* During `fsdocs watch`, the logo now links to the locally hosted site root (e.g. `http://localhost:8901/`) instead of the production URL, even when `<FsDocsLogoLink>` is set. Release builds are unaffected.
+* The `fsdocs watch` console no longer logs websocket connection chatter ("New websocket connection", "WebSocket disconnected", ...) on every page reload.
 
 ### Removed
 * Remove `docs/Dockerfile` (used for mybinder.org Binder integration) and mybinder badge links from documentation pages. The Binder integration relied on a deprecated .NET 7 SDK image and a deprecated `Microsoft.dotnet-interactive` version; mybinder.org support is discontinued.

build.fsx

@@ -1,4 +1,5 @@
-#r "nuget: Fun.Build, 1.0.4"
+#!/usr/bin/env -S dotnet fsi --
+#r "nuget: Fun.Build, 1.1.18"
 #r "nuget: Fake.IO.FileSystem, 6.0.0"
 #r "nuget: Ionide.KeepAChangelog, 0.1.8"
 

src/fsdocs-tool/BuildCommand.fs

@@ -27,7 +27,6 @@ open Suave.Sockets.Control
 open Suave.WebSocket
 open Suave.Operators
 open Suave.Filters
-open Suave.Logging
 open FSharp.Formatting.Markdown
 
 
@@ -860,30 +859,50 @@ module Serve =
 
     let connectedClients = ConcurrentDictionary<WebSocket, unit>()
 
-    let socketHandler (webSocket: WebSocket) (context: HttpContext) =
-        context.runtime.logger.info (Message.eventX "New websocket connection")
+    let socketHandler (webSocket: WebSocket) (_context: HttpContext) : SocketOp<unit> =
         connectedClients.TryAdd(webSocket, ()) |> ignore
 
-        socket {
-            let! msg = webSocket.read ()
+        Threading.Tasks.ValueTask<Result<unit, Sockets.Error>>(
+            task {
+                try
+                    // Block until the client sends a message or disconnects.
+                    let! msg = (webSocket.read ()).AsTask()
+
+                    match msg with
+                    | Ok(Close, _, _) ->
+                        let emptyResponse = [||] |> ByteSegment
+                        let! _ = (webSocket.send Close emptyResponse true).AsTask()
+                        ()
+                    | _ -> ()
+                with _ ->
+                    ()
 
-            match msg with
-            | Close, _, _ ->
-                context.runtime.logger.info (Message.eventX "Closing connection")
+                // Deregister the client however the connection ended, so reload
+                // broadcasts never touch a dead (and possibly recycled) socket.
                 connectedClients.TryRemove webSocket |> ignore
-                let emptyResponse = [||] |> ByteSegment
-                do! webSocket.send Close emptyResponse true
-            | _ -> ()
-        }
+
+                // Return Ok even when the client vanished without a close handshake,
+                // otherwise Suave writes a "WebSocket disconnected" line to the console.
+                return Ok()
+            }
+        )
 
     let broadCastReload (msg: string) =
         let msg = msg |> Encoding.UTF8.GetBytes |> ByteSegment
 
         connectedClients.Keys
         |> Seq.map (fun client ->
             async {
-                let! _ = client.send Text msg true
-                ()
+                try
+                    let! result = (client.send Text msg true).AsTask() |> Async.AwaitTask
+
+                    match result with
+                    | Ok() -> ()
+                    | Result.Error _ -> connectedClients.TryRemove client |> ignore
+                with _ ->
+                    // Suave 3 throws (e.g. ObjectDisposedException) when the client
+                    // disconnected without a close handshake; drop the stale client.
+                    connectedClients.TryRemove client |> ignore
             })
         |> Async.Parallel
         |> Async.Ignore
@@ -1312,7 +1331,8 @@ module Serve =
                   >=> Writers.setHeader "Expires" "0"
                   >=> Files.browseHome ]
 
-        startWebServerAsync serverConfig app |> snd |> Async.Start
+        // In Suave 3.x the server part of the tuple is a hot Task, no explicit start needed.
+        startWebServerAsync serverConfig app |> snd |> ignore
 
 /// Helpers for generating llms.txt and llms-full.txt content.
 module internal LlmsTxt =
@@ -1648,6 +1668,21 @@ type CoreBuildOptions(watch) =
         // See https://github.com/ionide/proj-info/issues/123
         System.Environment.SetEnvironmentVariable("DOTNET_HOST_PATH", prevDotnetHostPath)
 
+        // In watch mode the logo must link to the locally hosted site, even when
+        // <FsDocsLogoLink> is set to a production URL for the published site.
+        let overrideLogoLinkForWatch substitutions =
+            if watch then
+                substitutions
+                |> List.map (fun (pk, v) ->
+                    if pk = ParamKeys.``fsdocs-logo-link`` then
+                        (pk, root)
+                    else
+                        (pk, v))
+            else
+                substitutions
+
+        let docsSubstitutions = overrideLogoLinkForWatch docsSubstitutions
+
         if crackedProjects.Length > 0 then
             printfn ""
             printfn "Inputs for API Docs:"
@@ -1725,7 +1760,7 @@ type CoreBuildOptions(watch) =
                     XmlFile = None
                     SourceRepo = sourceRepo
                     SourceFolder = Some sourceFolder
-                    Substitutions = Some projectParameters
+                    Substitutions = Some(overrideLogoLinkForWatch projectParameters)
                     MarkdownComments = this.mdcomments || projectMarkdownComments
                     Warn = projectWarn
                     PublicOnly = not this.nonpublic