Make Vert.x test server Resource repeatable so the flaky-test retry works (#5411)

## Problem

The flaky-WebSocket-test retry added in #5410 (`TestSuite.retries`) did
**not** actually rescue the Vert.x WS flake. On CI the retry ran but
every attempt after the first failed **instantly** with:

```
ERROR DefaultCreateServerTest - Starting server failed because of null
java.lang.IllegalStateException
    at io.vertx.core.http.impl.CleanableHttpServer.listen(CleanableHttpServer.java:61)
```

## Root cause

The three Vert.x **test** interpreters build the HTTP server **eagerly,
outside** the `Resource.make` acquire:

```scala
val server = vertx.createHttpServer(...).requestHandler(router)  // captured once
val listenIO = vertxFutureToIo(server.listen(0))
Resource.make(listenIO)(...)
```

The retry re-runs the whole test, re-using the same server `Resource`,
which calls `listen()` a **second time on the same server instance**.
Vert.x 5's `CleanableHttpServer.listen` throws `IllegalStateException`
(empty message → logged as "because of null") when its `listenContext`
is already set. So the per-test server Resource simply wasn't repeatable
— the shared Vert.x was never actually broken.

## Fix

Create the server **inside** the acquire, so each acquire (and each
retry) gets a fresh server:

```scala
val listenIO = IO.delay {
  val router = Router.router(vertx)
  val _ = route(router)
  vertx.createHttpServer(...).requestHandler(router)
}.flatMap(server => vertxFutureToIo(server.listen(0)))
Resource.make(listenIO)(s => vertxFutureToIo(s.close()).void).map(_.actualPort())
```

Applied to `VertxTestServerInterpreter`,
`CatsVertxTestServerInterpreter`, `ZioVertxTestServerInterpreter`.

## Test

`ServerResourceRepeatableSpec` acquires the server Resource twice (what
the retry does). It throws the exact `IllegalStateException` on the old
eager code and passes with this fix.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: adamw

server/vertx-server/cats/src/test/scala/sttp/tapir/server/vertx/cats/CatsVertxTestServerInterpreter.scala

@@ -30,11 +30,17 @@ class CatsVertxTestServerInterpreter(vertx: Vertx, dispatcher: Dispatcher[IO])
       route: Router => Route,
       gracefulShutdownTimeout: Option[FiniteDuration]
   ): Resource[IO, Port] = {
-    val router = Router.router(vertx)
-    route(router)
-    // the maxFormAttributeSize must be higher than in ServerMultipartTests.maxContentLengthTests
-    val server = vertx.createHttpServer(new HttpServerOptions().setPort(0).setMaxFormAttributeSize(100000)).requestHandler(router)
-    val listenIO = ioFromVFuture(server.listen(0))
+    // The server is created inside the Resource's acquire (not eagerly), so that the Resource can be safely re-run:
+    // the flaky-WebSocket-test retry re-uses this Resource, and Vert.x's CleanableHttpServer.listen throws
+    // IllegalStateException if listen() is called a second time on the same server instance.
+    val listenIO = IO
+      .delay {
+        val router = Router.router(vertx)
+        val _ = route(router)
+        // the maxFormAttributeSize must be higher than in ServerMultipartTests.maxContentLengthTests
+        vertx.createHttpServer(new HttpServerOptions().setPort(0).setMaxFormAttributeSize(100000)).requestHandler(router)
+      }
+      .flatMap(server => ioFromVFuture(server.listen(0)))
     // Vertx doesn't offer graceful shutdown with timeout OOTB
     Resource.make(listenIO)(s => ioFromVFuture(s.close).void).map(_.actualPort())
   }

server/vertx-server/cats/src/test/scala/sttp/tapir/server/vertx/cats/ServerResourceRepeatableSpec.scala

@@ -0,0 +1,30 @@
+package sttp.tapir.server.vertx.cats
+
+import cats.effect.IO
+import cats.effect.std.Dispatcher
+import cats.effect.unsafe.implicits.global
+import io.vertx.core.Vertx
+import io.vertx.ext.web.{Route, Router}
+import org.scalatest.funsuite.AnyFunSuite
+
+// Guards that the per-test server Resource can be acquired more than once. The flaky-WebSocket-test retry
+// (TestSuite.retries) re-runs the whole test, hence re-uses this Resource; if the server were created eagerly
+// (outside the acquire) rather than inside it, the second listen() would hit Vert.x's CleanableHttpServer guard
+// and throw IllegalStateException, defeating the retry. See CatsVertxTestServerInterpreter.server.
+class ServerResourceRepeatableSpec extends AnyFunSuite {
+  test("server Resource can be acquired twice without IllegalStateException") {
+    val vertx = Vertx.vertx()
+    try {
+      Dispatcher
+        .parallel[IO]
+        .use { dispatcher =>
+          val interpreter = new CatsVertxTestServerInterpreter(vertx, dispatcher)
+          val trivialRoute: Router => Route = router => router.route()
+          val res = interpreter.server(trivialRoute, None)
+          // first use = original run; second use = the retry
+          res.use(_ => IO.unit) >> res.use(port => IO(assert(port > 0)))
+        }
+        .unsafeRunSync()
+    } finally { val _ = vertx.close() }
+  }
+}

server/vertx-server/src/test/scala/sttp/tapir/server/vertx/VertxTestServerInterpreter.scala

@@ -28,11 +28,18 @@ class VertxTestServerInterpreter(vertx: Vertx)
       route: Router => Route,
       gracefulShutdownTimeout: Option[FiniteDuration]
   ): Resource[IO, Port] = {
-    val router = Router.router(vertx)
-    // the maxFormAttributeSize must be higher than in ServerMultipartTests.maxContentLengthTests
-    val server = vertx.createHttpServer(new HttpServerOptions().setPort(0).setMaxFormAttributeSize(100000)).requestHandler(router)
-    val listenIO = vertxFutureToIo(server.listen(0))
-    route(router)
+    // The server is created inside the Resource's acquire (not eagerly), so that the Resource can be safely re-run:
+    // the flaky-WebSocket-test retry re-uses this Resource, and Vert.x's CleanableHttpServer.listen throws
+    // IllegalStateException if listen() is called a second time on the same server instance.
+    val listenIO = IO
+      .delay {
+        val router = Router.router(vertx)
+        // the maxFormAttributeSize must be higher than in ServerMultipartTests.maxContentLengthTests
+        val server = vertx.createHttpServer(new HttpServerOptions().setPort(0).setMaxFormAttributeSize(100000)).requestHandler(router)
+        val _ = route(router)
+        server
+      }
+      .flatMap(server => vertxFutureToIo(server.listen(0)))
     // Vertx doesn't offer graceful shutdown with timeout OOTB
     Resource.make(listenIO)(s => vertxFutureToIo(s.close()).void).map(s => s.actualPort())
   }

server/vertx-server/zio/src/test/scala/sttp/tapir/server/vertx/zio/ZioVertxTestServerInterpreter.scala

@@ -27,12 +27,18 @@ class ZioVertxTestServerInterpreter(vertx: Vertx)
       route: Router => Route,
       gracefulShutdownTimeout: Option[FiniteDuration]
   ): Resource[IO, Port] = {
-    val router = Router.router(vertx)
-    // the maxFormAttributeSize must be higher than in ServerMultipartTests.maxContentLengthTests
-    val server = vertx.createHttpServer(new HttpServerOptions().setPort(0).setMaxFormAttributeSize(100000)).requestHandler(router)
-    route(router)
-
-    val listenIO = VertxTestServerInterpreter.vertxFutureToIo(server.listen(0))
+    // The server is created inside the Resource's acquire (not eagerly), so that the Resource can be safely re-run:
+    // the flaky-WebSocket-test retry re-uses this Resource, and Vert.x's CleanableHttpServer.listen throws
+    // IllegalStateException if listen() is called a second time on the same server instance.
+    val listenIO = IO
+      .delay {
+        val router = Router.router(vertx)
+        // the maxFormAttributeSize must be higher than in ServerMultipartTests.maxContentLengthTests
+        val server = vertx.createHttpServer(new HttpServerOptions().setPort(0).setMaxFormAttributeSize(100000)).requestHandler(router)
+        val _ = route(router)
+        server
+      }
+      .flatMap(server => VertxTestServerInterpreter.vertxFutureToIo(server.listen(0)))
     // Vertx doesn't offer graceful shutdown with timeout OOTB
     Resource.make(listenIO)(server => VertxTestServerInterpreter.vertxFutureToIo(server.close).void).map(_.actualPort())
   }