Netty docs

Author: adamw

doc/server/netty.md

@@ -3,12 +3,12 @@
 To expose an endpoint using a [Netty](https://netty.io)-based server, first add the following dependency:
 
 ```scala
-// if you are using Future or just exploring:
-"com.softwaremill.sttp.tapir" %% "tapir-netty-server" % "@VERSION@"
-
-// if you want to use Java 21 Loom virtual threads in direct style:
+// if you want to use Java 21+ Virtual Threads & direct-style:
 "com.softwaremill.sttp.tapir" %% "tapir-netty-server-sync" % "@VERSION@"
 
+// if you are using Future:
+"com.softwaremill.sttp.tapir" %% "tapir-netty-server" % "@VERSION@"
+
 // if you are using cats-effect:
 "com.softwaremill.sttp.tapir" %% "tapir-netty-server-cats" % "@VERSION@"
 
@@ -18,18 +18,20 @@ To expose an endpoint using a [Netty](https://netty.io)-based server, first add
 
 Then, use:
 
+- `NettySyncServer().addEndpoints` to expose direct-style server endpoints (using Virtual Threads).
 - `NettyFutureServer().addEndpoints` to expose `Future`-based server endpoints.
-- `NettySyncServer().addEndpoints` to expose `Loom`-based server endpoints.
-- `NettyCatsServer().addEndpoints` to expose `F`-based server endpoints, where `F` is any cats-effect supported effect. [Streaming](../endpoint/streaming.md) request and response bodies is supported with fs2.
-- `NettyZioServer().addEndpoints` to expose `ZIO`-based server endpoints, where `R` represents ZIO requirements supported effect. Streaming is supported with ZIO Streams.
+- `NettyCatsServer().addEndpoints` to expose `F`-based server endpoints, where `F` is any cats-effect supported effect.
+  [Streaming](../endpoint/streaming.md) request and response bodies is supported with fs2.
+- `NettyZioServer().addEndpoints` to expose `ZIO`-based server endpoints, where `R` represents ZIO requirements
+  supported effect. Streaming is supported with ZIO Streams.
 
 These methods require a single, or a list of `ServerEndpoint`s, which can be created by adding [server logic](logic.md)
 to an endpoint.
 
 For example:
 
 ```scala mdoc:compile-only
-import sttp.tapir.*
+import sttp.tapir.*  
 import sttp.tapir.server.netty.{NettyFutureServer, NettyFutureServerBinding}
 import scala.concurrent.ExecutionContext.Implicits.global
 import scala.concurrent.Future
@@ -46,23 +48,27 @@ val binding: Future[NettyFutureServerBinding] =
 
 ## Direct-style
 
-The `tapir-netty-server-sync` server uses `Identity[T]` as its wrapper effect for compatibility; `Identity[A]` means in 
+The `tapir-netty-server-sync` server uses `Identity[T]` as its wrapper effect for compatibility; `Identity[A]` means in
 fact just `A`, representing direct style. It is available only for Scala 3.
 
-See [examples/helloWorldNettySyncServer.scala](https://github.com/softwaremill/tapir/blob/master/examples/src/main/scala/sttp/tapir/examples/helloWorldNettySyncServer.scala) for a full example.
+See
+[examples/helloWorldNettySyncServer.scala](https://github.com/softwaremill/tapir/blob/master/examples/src/main/scala/sttp/tapir/examples/helloWorldNettySyncServer.scala)
+for a full example.
 
-To provide server logic for an endpoint when using the `-sync` server, you can use the dedicated `handle`
-methods, and its variants. This provides better type inference.
+To provide server logic for an endpoint when using the `-sync` server, you can use the dedicated `handle` methods, and
+its variants. This provides better type inference.
 
 To learn more about handling concurrency with Ox, see the [documentation](https://ox.softwaremill.com/).
 
 ## Configuration
 
-The interpreter can be configured by providing an `NettyFutureServerOptions` value, see [server options](options.md) for
+The interpreters can be configured by providing an `Netty[Sync|Future|...]ServerOptions` value, see [server
+options](options.md) for
 details.
 
-Some options can be configured directly using a `NettyFutureServer` instance, such as the host and port. Others
-can be passed using the `NettyFutureServer(options)` methods. Options may also be overridden when adding endpoints.
+Some options can be configured directly using a `Netty[Sync|Future|...]Server` instance, such as the host and port.
+Others can be passed using the `Netty[Sync|Future|...]Server(options)` methods. Options may also be overridden when
+adding endpoints.
 For example:
 
 ```scala mdoc:compile-only
@@ -83,15 +89,37 @@ NettyFutureServer(NettyConfig.default.socketBacklog(256))
 Unlike other server interpreters, the Netty-based servers are by default configured to return a 404, in case none of
 the given endpoints match a request. This can be changed by using a different `RejectHandler`.
 
-This is due to the fact that usually no other routes (not generated from endpoints) are added to a Netty server.
+This is due to the fact that usually no other routes (other than generated from Tapir's endpoints) are added to a Netty server.
+```
+
+### Server socket configuration
+
+`NettyConfig` exposes a number of configuration options which allows to customise the server socket, such as:
+* request timeout
+* connection timeout
+* linger timeout
+* graceful shutdown timeout: when stopped e.g. using `NettyFutureServerBinding.stop()`, it's ensured that the server
+  will wait at most 10 seconds for in-flight requests to complete, while rejecting all new requests with 503 during this
+  period; afterwards, all server resources are closed
+* server header
+* maximum number of connections
+* custom netty pipeline & low-level logging handlers
+
+For example, to change the request timeout:
+
+```scala mdoc:compile-only
+import sttp.tapir.server.netty.NettyConfig
+import scala.concurrent.duration.*
+
+val config = NettyConfig.default.requestTimeout(5.seconds)
 ```
 
 ## Web sockets
 
 ### tapir-netty-server-cats
 
-The Cats Effects interpreter supports web sockets, with pipes of type `fs2.Pipe[F, REQ, RESP]`. See [web sockets](../endpoint/websockets.md) 
-for more details.
+The Cats Effects interpreter supports web sockets, with pipes of type `fs2.Pipe[F, REQ, RESP]`. See [web
+sockets](../endpoint/websockets.md) for more details.
 
 To create a web socket endpoint, use Tapir's `out(webSocketBody)` output type:
 
@@ -155,8 +183,11 @@ object WebSocketsNettyCatsServer extends ResourceApp.Forever {
 
 ### tapir-netty-server-sync
 
-In the Loom-based backend, Tapir uses [Ox](https://ox.softwaremill.com) to manage concurrency, and your transformation pipeline should be represented as `Flow[A] => Flow[B]`. Any forks started within this function will be run under a safely isolated internal scope.
-See [examples/websocket/WebSocketNettySyncServer.scala](https://github.com/softwaremill/tapir/blob/master/examples/src/main/scala/sttp/tapir/examples/websocket/WebSocketNettySyncServer.scala) for a full example.
+In the Loom-based backend, Tapir uses [Ox](https://ox.softwaremill.com) to manage concurrency, and your transformation
+pipeline should be represented as `Flow[A] => Flow[B]`. Any forks started within this function will be run under a
+safely isolated internal scope. See
+[examples/websocket/WebSocketNettySyncServer.scala](https://github.com/softwaremill/tapir/blob/master/examples/src/main/scala/sttp/tapir/examples/websocket/WebSocketNettySyncServer.scala)
+for a full example.
 
 ```{note}
 The pipeline transforms a source of incoming web socket messages (received from the client), into a source of outgoing web socket messages (which will be sent to the client), within some concurrency scope. Once the incoming source is done, the client has closed the connection. In that case, remember to close the outgoing source as well: otherwise the scope will leak and won't be closed. An error will be logged if the outgoing channel is not closed within a timeout after a close frame is received.
@@ -166,7 +197,8 @@ The pipeline transforms a source of incoming web socket messages (received from
 
 ### tapir-netty-server-sync
 
-The interpreter supports [SSE (Server Sent Events)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events). 
+The interpreter supports [SSE (Server Sent
+Events)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events). 
 
 For example, to define an endpoint that returns event stream:
 
@@ -189,21 +221,6 @@ val sseFlow = Flow
 val sseServerEndpoint = sseEndpoint.handleSuccess(_ => sseFlow)
 ```
 
-## Graceful shutdown
-
-A Netty server can be gracefully closed using the function `NettyFutureServerBinding.stop()` (and analogous functions available in Cats and ZIO bindings). This function ensures that the server will wait at most 10 seconds for in-flight requests to complete, while rejecting all new requests with 503 during this period. Afterwards, it closes all server resources.
-You can customize this behavior in `NettyConfig`:
-
-```scala mdoc:compile-only
-import sttp.tapir.server.netty.NettyConfig
-import scala.concurrent.duration.*
-
-// adjust the waiting time to your needs
-val config = NettyConfig.default.withGracefulShutdownTimeout(5.seconds)
-// or if you don't want the server to wait for in-flight requests
-val config2 = NettyConfig.default.noGracefulShutdown
-```
-
 ## Domain socket support
 
 There is possibility to use Domain socket instead of TCP for handling traffic.