Framework smoke matrix: the Spring WebFlux agent cells

The Spring program runs as a reactive web application with --web
reactive: Reactor Netty on server.port with the SDK's WebFlux host
(acp-http-webflux) routed at /acp. smoke.json gains a spring-webflux
framework that reuses programs/spring with that flag, for http and ws,
and GenConfigs learns two optional framework keys: agentArgs (flags the
program's agent.sh gets before --transport) and agentName (the @AcpAgent
name the initialize step expects). Generated: fw-spring-webflux-agent-http,
fw-spring-webflux-agent-ws and load-10-fw-spring-webflux.

Author: Mark Pollack

integration-testing/GenConfigs.java

@@ -558,6 +558,11 @@ void validateSmoke(Set<String> ids, Set<String> langs, Set<String> transports) {
 			if (!Files.exists(root.resolve(f.getValue().path("dir").asText()).resolve("launch/agent.sh"))) {
 				problems.add("smoke.json: " + f.getKey() + ".dir has no launch/agent.sh");
 			}
+			for (String key : List.of("agentArgs", "agentName")) {
+				if (f.getValue().has(key) && !f.getValue().path(key).isTextual()) {
+					problems.add("smoke.json: " + f.getKey() + "." + key + " must be a string");
+				}
+			}
 		});
 	}
 
@@ -604,6 +609,12 @@ void generateSmoke(Map<String, String> out) throws Exception {
 		}
 	}
 
+	/** The framework program's extra agent flags (smoke.json agentArgs), with a leading space, or none. */
+	static String agentArgs(JsonNode fw) {
+		String args = fw.path("agentArgs").asText("").trim();
+		return args.isEmpty() ? "" : " " + args;
+	}
+
 	String fwBuild(JsonNode fw) {
 		return "IT_ROOT=\"${ROOT}\" MVNW=\"${MVNW}\" ACP_VERSION=\"${ACP_VERSION}\" CACHE=\"${CACHE}\" ${ROOT}/"
 				+ fw.path("dir").asText() + "/launch/build.sh";
@@ -640,7 +651,8 @@ ObjectNode smokeCell(String name, String framework, JsonNode fw, String peer, St
 			a.put("role", "server");
 			a.put("dir", "${ROOT}/" + agentDir);
 			a.put("build", agentBuild);
-			a.put("run", "${ROOT}/" + agentDir + "/launch/agent.sh --transport " + transport + " --port ${PORT}");
+			a.put("run", "${ROOT}/" + agentDir + "/launch/agent.sh" + (agentSide ? agentArgs(fw) : "") + " --transport "
+					+ transport + " --port ${PORT}");
 			ObjectNode aenv = a.putObject("env");
 			env.forEach(aenv::put);
 			ObjectNode ready = a.putObject("ready");
@@ -662,7 +674,8 @@ ObjectNode smokeCell(String name, String framework, JsonNode fw, String peer, St
 		ObjectNode cenv = cl.putObject("env");
 		cenv.put("STEPS", String.join(",", ids));
 		if (stdio) {
-			cenv.put("AGENT_CMD", "${ROOT}/" + agentDir + "/launch/agent.sh --transport stdio");
+			cenv.put("AGENT_CMD", "${ROOT}/" + agentDir + "/launch/agent.sh" + (agentSide ? agentArgs(fw) : "")
+					+ " --transport stdio");
 		}
 		env.forEach(cenv::put);
 		cl.put("timeoutSec", clientTimeout);
@@ -683,7 +696,7 @@ ObjectNode smokeCell(String name, String framework, JsonNode fw, String peer, St
 			putLines(as, "forbiddenOutput", forbidden);
 			Map<String, Set<String>> patterns = new LinkedHashMap<>();
 			patterns.put("client", new LinkedHashSet<>(List.of("STEP init\\.initialize PASS .*\"name\":\"interop-"
-					+ framework + "-agent\"")));
+					+ fw.path("agentName").asText(framework) + "-agent\"")));
 			putLines(as, "requiredPatterns", patterns);
 		}
 		ArrayNode checks = as.putArray("checks");
@@ -712,7 +725,8 @@ ObjectNode smokeLoad(String name, String framework, JsonNode fw) {
 		a.put("role", "server");
 		a.put("dir", "${ROOT}/" + fw.path("dir").asText());
 		a.put("build", fwBuild(fw));
-		a.put("run", "${ROOT}/" + fw.path("dir").asText() + "/launch/agent.sh --transport http --port ${PORT}");
+		a.put("run", "${ROOT}/" + fw.path("dir").asText() + "/launch/agent.sh" + agentArgs(fw)
+				+ " --transport http --port ${PORT}");
 		a.putObject("env").put("JAVA_OPTS", load.path("serverJavaOpts").asText("-Xmx512m"));
 		ObjectNode ready = a.putObject("ready");
 		ready.put("line", "READY");

integration-testing/README.md

@@ -20,7 +20,7 @@ There are four kinds of scenarios:
 - **Conformance scenarios**, `configs/conf-java-*.json`: the raw JSON-RPC driver
   (`programs/raw`) against the Java agent and client, generated by `programs/raw/gen_conf.py`.
 - **Framework smoke cells**, `configs/fw-*.json` and `configs/load-10-fw-*.json`: the SDK hosted
-  by Spring Boot, Micronaut and Quarkus against the TypeScript SDK, generated from `smoke.json` by
+  by Spring Boot (servlet and WebFlux), Micronaut and Quarkus against the TypeScript SDK, generated from `smoke.json` by
   `GenConfigs.java` ([Framework smoke matrix](#framework-smoke-matrix)).
 - **Load scenarios**, `configs/load-*.json`, hand-written (except `load-10-fw-*`).
 
@@ -158,13 +158,17 @@ the commit being released (`framework-smoke.yml`, or the local command below), n
 | Framework | Agent transports | Client | Program |
 |---|---|---|---|
 | Spring Boot 4.1 | stdio (`spring.main.keep-alive=true`), HTTP and WebSocket (the SDK servlet, `acp-http-servlet`, on `server.port` in a servlet web application) | HTTP | [programs/spring](programs/spring) |
+| Spring Boot 4.1, WebFlux (`spring-webflux`) | HTTP and WebSocket (the SDK's WebFlux host, `acp-http-webflux`, routed on `server.port` by Reactor Netty in a reactive web application) | none | [programs/spring](programs/spring), `--web reactive` |
 | Micronaut 4 | stdio, HTTP, WebSocket (the SDK listener) | HTTP | [programs/micronaut](programs/micronaut) |
 | Quarkus | stdio, HTTP, WebSocket (the Quarkus HTTP server); one package per build-time transport | HTTP | [programs/quarkus](programs/quarkus) |
 
 The agent handlers ([programs/framework/.../SmokeAgent.java](programs/framework/src/main/java/interop/framework/SmokeAgent.java))
 and the client steps ([SmokeClient.java](programs/framework/src/main/java/interop/framework/SmokeClient.java))
 are shared sources that every framework program compiles in; each framework adds only an
-`@AcpAgent` subclass with its own bean annotation and a main class. To run the whole matrix,
+`@AcpAgent` subclass with its own bean annotation and a main class. A framework entry in
+`smoke.json` may reuse another's program with `agentArgs` (flags its `agent.sh` gets before
+`--transport`, as `spring-webflux` runs `programs/spring` with `--web reactive`) and `agentName`
+(the `@AcpAgent` name the `init.initialize` step expects, `interop-<agentName>-agent`). To run the whole matrix,
 locally or against another branch:
 
 ```bash

integration-testing/configs/fw-spring-webflux-agent-http.json

@@ -0,0 +1,69 @@
+{
+  "name": "fw-spring-webflux-agent-http",
+  "description": "typescript client -> spring-webflux-hosted java agent over http, 14 smoke steps (generated from smoke.json)",
+  "timeoutSec": 370,
+  "peers": [
+    "typescript-sdk"
+  ],
+  "processes": [
+    {
+      "name": "agent",
+      "language": "java",
+      "role": "server",
+      "dir": "${ROOT}/programs/spring",
+      "build": "IT_ROOT=\"${ROOT}\" MVNW=\"${MVNW}\" ACP_VERSION=\"${ACP_VERSION}\" CACHE=\"${CACHE}\" ${ROOT}/programs/spring/launch/build.sh",
+      "run": "${ROOT}/programs/spring/launch/agent.sh --web reactive --transport http --port ${PORT}",
+      "env": {
+        "TS_SDK": "${peer.typescript-sdk}"
+      },
+      "ready": {
+        "line": "READY",
+        "timeoutSec": 90
+      }
+    },
+    {
+      "name": "client",
+      "language": "typescript",
+      "role": "client",
+      "dir": "${ROOT}/programs/node",
+      "build": "IT_ROOT=\"${ROOT}\" MVNW=\"${MVNW}\" ACP_VERSION=\"${ACP_VERSION}\" CACHE=\"${CACHE}\" TS_SDK=\"${peer.typescript-sdk}\" ${ROOT}/programs/node/launch/build.sh",
+      "run": "${ROOT}/programs/node/launch/client.sh --transport http --url http://127.0.0.1:${PORT}/acp",
+      "env": {
+        "STEPS": "init.initialize,init.agent-capabilities,init.agent-info,session.new,session.load,session.multi,update.agent_message_chunk,perm.selected,elicit.form,cancel.prompt,ext.client-request,error.method-not-found,http.reconnect,conn.close",
+        "TS_SDK": "${peer.typescript-sdk}"
+      },
+      "timeoutSec": 190
+    }
+  ],
+  "assertions": {
+    "requiredOutput": {
+      "agent": [
+        "STEP agent.perm.selected PASS",
+        "STEP agent.elicit.form PASS",
+        "STEP agent.cancel.prompt PASS"
+      ]
+    },
+    "forbiddenOutput": {
+      "agent": [
+        " ERROR ",
+        " WARN "
+      ]
+    },
+    "requiredPatterns": {
+      "client": [
+        "STEP init\\.initialize PASS .*\"name\":\"interop-spring-agent\""
+      ]
+    },
+    "checks": [
+      "client RESULT pass == 14",
+      "client RESULT fail == 0"
+    ],
+    "expectedFailures": [],
+    "report": {
+      "client": [
+        "TIMEOUT"
+      ]
+    }
+  },
+  "comment": "GENERATED by GenConfigs.java from smoke.json, steps.json and matrix.json; do not edit, regenerate."
+}

integration-testing/configs/fw-spring-webflux-agent-ws.json

@@ -0,0 +1,69 @@
+{
+  "name": "fw-spring-webflux-agent-ws",
+  "description": "typescript client -> spring-webflux-hosted java agent over ws, 13 smoke steps (generated from smoke.json)",
+  "timeoutSec": 365,
+  "peers": [
+    "typescript-sdk"
+  ],
+  "processes": [
+    {
+      "name": "agent",
+      "language": "java",
+      "role": "server",
+      "dir": "${ROOT}/programs/spring",
+      "build": "IT_ROOT=\"${ROOT}\" MVNW=\"${MVNW}\" ACP_VERSION=\"${ACP_VERSION}\" CACHE=\"${CACHE}\" ${ROOT}/programs/spring/launch/build.sh",
+      "run": "${ROOT}/programs/spring/launch/agent.sh --web reactive --transport ws --port ${PORT}",
+      "env": {
+        "TS_SDK": "${peer.typescript-sdk}"
+      },
+      "ready": {
+        "line": "READY",
+        "timeoutSec": 90
+      }
+    },
+    {
+      "name": "client",
+      "language": "typescript",
+      "role": "client",
+      "dir": "${ROOT}/programs/node",
+      "build": "IT_ROOT=\"${ROOT}\" MVNW=\"${MVNW}\" ACP_VERSION=\"${ACP_VERSION}\" CACHE=\"${CACHE}\" TS_SDK=\"${peer.typescript-sdk}\" ${ROOT}/programs/node/launch/build.sh",
+      "run": "${ROOT}/programs/node/launch/client.sh --transport ws --url ws://127.0.0.1:${PORT}/acp",
+      "env": {
+        "STEPS": "init.initialize,init.agent-capabilities,init.agent-info,session.new,session.load,session.multi,update.agent_message_chunk,perm.selected,elicit.form,cancel.prompt,ext.client-request,error.method-not-found,conn.close",
+        "TS_SDK": "${peer.typescript-sdk}"
+      },
+      "timeoutSec": 185
+    }
+  ],
+  "assertions": {
+    "requiredOutput": {
+      "agent": [
+        "STEP agent.perm.selected PASS",
+        "STEP agent.elicit.form PASS",
+        "STEP agent.cancel.prompt PASS"
+      ]
+    },
+    "forbiddenOutput": {
+      "agent": [
+        " ERROR ",
+        " WARN "
+      ]
+    },
+    "requiredPatterns": {
+      "client": [
+        "STEP init\\.initialize PASS .*\"name\":\"interop-spring-agent\""
+      ]
+    },
+    "checks": [
+      "client RESULT pass == 13",
+      "client RESULT fail == 0"
+    ],
+    "expectedFailures": [],
+    "report": {
+      "client": [
+        "TIMEOUT"
+      ]
+    }
+  },
+  "comment": "GENERATED by GenConfigs.java from smoke.json, steps.json and matrix.json; do not edit, regenerate."
+}

integration-testing/configs/load-10-fw-spring-webflux.json

@@ -0,0 +1,56 @@
+{
+  "name": "load-10-fw-spring-webflux",
+  "description": "10 connections x 10 prompts against the spring-webflux-hosted agent over http, two streamed updates each (generated from smoke.json)",
+  "timeoutSec": 420,
+  "processes": [
+    {
+      "name": "server",
+      "language": "java",
+      "role": "server",
+      "dir": "${ROOT}/programs/spring",
+      "build": "IT_ROOT=\"${ROOT}\" MVNW=\"${MVNW}\" ACP_VERSION=\"${ACP_VERSION}\" CACHE=\"${CACHE}\" ${ROOT}/programs/spring/launch/build.sh",
+      "run": "${ROOT}/programs/spring/launch/agent.sh --web reactive --transport http --port ${PORT}",
+      "env": {
+        "JAVA_OPTS": "-Xmx512m"
+      },
+      "ready": {
+        "line": "READY",
+        "timeoutSec": 90
+      }
+    },
+    {
+      "name": "clients",
+      "language": "java",
+      "role": "client",
+      "dir": "${ROOT}/programs/java",
+      "build": "IT_ROOT=\"${ROOT}\" MVNW=\"${MVNW}\" ACP_VERSION=\"${ACP_VERSION}\" CACHE=\"${CACHE}\" ${ROOT}/programs/java/launch/build.sh",
+      "run": "java -Xmx1g -Dacp.client.level=INFO -cp target/classes:$(cat target/classpath.txt) load.LoadClients http://127.0.0.1:${PORT}/acp 10 10 perclient",
+      "timeoutSec": 300
+    }
+  ],
+  "assertions": {
+    "requiredOutput": {
+      "clients": [
+        "PEAK_REACHED",
+        "CLOSED"
+      ]
+    },
+    "forbiddenOutput": {
+      "clients": [
+        "ERROR ",
+        "CLOSE_ERROR"
+      ],
+      "server": [
+        " ERROR "
+      ]
+    },
+    "checks": [
+      "clients RESULT errors == 0",
+      "clients RESULT ok == expected",
+      "clients RESULT expected == 100",
+      "clients RESULT updates == 2*ok",
+      "clients RESULT close_errors == 0"
+    ]
+  },
+  "comment": "GENERATED by GenConfigs.java from smoke.json, steps.json and matrix.json; do not edit, regenerate."
+}

integration-testing/programs/spring/launch/agent.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Starts the Spring Boot smoke agent: --transport stdio | --transport http|ws --port <port>.
+# Starts the Spring Boot smoke agent: [--web servlet|reactive] --transport stdio | --transport http|ws --port <port>.
 # Launcher contract: integration-testing/README.md, "Contracts". Prints nothing itself: on stdio,
 # stdout is the protocol stream (the application logs to stderr). JAVA_OPTS, if set, is passed on.
 set -euo pipefail

integration-testing/programs/spring/pom.xml

@@ -2,7 +2,8 @@
 <!--
   The Spring Boot programs of the framework smoke cells (integration-testing/smoke.json): an
   @AcpAgent bean served by acp-spring-boot-starter (interop.spring.agent: stdio, or Streamable HTTP
-  on the servlet the starter mounts on server.port), and an ACP client bean
+  and WebSocket on server.port, through the servlet in a servlet web application or the WebFlux
+  host in a reactive one), and an ACP client bean
   the starter builds from spring.acp.client.* (interop.spring.client). The agent's handlers and the
   client's steps are the shared sources of programs/framework. Not a module of the SDK reactor:
   launch/build.sh builds it against the SDK installed from this checkout (-Dacp.version) and the
@@ -54,6 +55,17 @@
             <artifactId>acp-http-servlet</artifactId>
             <version>${acp.version}</version>
         </dependency>
+        <!-- With the reactive web flag, a WebFlux application: the SDK's WebFlux host routed on the
+             application's own Reactor Netty server (server.port), Streamable HTTP and WebSocket -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-webflux</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.agentclientprotocol</groupId>
+            <artifactId>acp-http-webflux</artifactId>
+            <version>${acp.version}</version>
+        </dependency>
     </dependencies>
 
     <build>

integration-testing/programs/spring/src/main/java/interop/spring/agent/SpringAgentApp.java

@@ -10,32 +10,37 @@
 /**
  * The launcher contract (integration-testing/README.md, "Contracts") over a Spring Boot 4
  * application whose {@code @AcpAgent} bean ({@link SpringSmokeAgent}) acp-spring-boot-starter
- * serves: {@code --transport stdio}, or {@code --transport http --port <port>}, which runs a
- * servlet web application on {@code server.port} with the SDK's Streamable HTTP servlet mounted at
- * {@code /acp}, and prints {@code READY <port>} once it accepts connections. This class only maps
- * the flags onto Spring properties. Over stdio the application is not a web application, is kept
+ * serves: {@code --transport stdio}, or {@code --transport http|ws --port <port>}, which runs a
+ * web application on {@code server.port} with the endpoint at {@code /acp} (Streamable HTTP and
+ * the WebSocket upgrade on that one path) and prints {@code READY <port>} once it accepts
+ * connections. {@code --web servlet} (the default) is a servlet web application with the SDK's
+ * servlet ({@code acp-http-servlet}) on Tomcat; {@code --web reactive} a WebFlux application with
+ * the SDK's WebFlux host ({@code acp-http-webflux}) on Reactor Netty. This class only maps the
+ * flags onto Spring properties. Over stdio the application is not a web application, is kept
  * alive by {@code spring.main.keep-alive} and exits when its input ends
  * ({@code spring.acp.agent.shutdown-on-transport-end}); over HTTP it runs until SIGTERM.
- *
- * <p>{@code --transport ws} is refused: the servlet takes no WebSocket upgrades on
- * {@code server.port} yet (TODO: the WebSocket cell, smoke.json "pendingAgentTransports").
  */
 @SpringBootApplication
 public class SpringAgentApp {
 
 	public static void main(String[] args) {
 		String transport = null;
 		String port = "0";
+		String web = "servlet";
 		for (int i = 0; i < args.length; i++) {
 			switch (args[i]) {
 				case "--transport" -> transport = value(args, ++i);
 				case "--port" -> port = value(args, ++i);
+				case "--web" -> web = value(args, ++i);
 				default -> usage("unknown flag " + args[i]);
 			}
 		}
 		if (transport == null) {
 			usage("--transport is required");
 		}
+		if (!"servlet".equals(web) && !"reactive".equals(web)) {
+			usage("unsupported --web " + web + " (servlet or reactive)");
+		}
 		boolean stdio = "stdio".equals(transport);
 		if (!stdio && !"http".equals(transport) && !"ws".equals(transport)) {
 			usage("unsupported transport " + transport + " (the Spring agent serves stdio, http and ws)");
@@ -48,10 +53,10 @@ public static void main(String[] args) {
 			properties.put("spring.acp.agent.transport.type", "stdio");
 		}
 		else {
-			properties.put("spring.main.web-application-type", "servlet");
+			properties.put("spring.main.web-application-type", web);
 			properties.put("server.address", "127.0.0.1");
 			properties.put("server.port", port);
-			// http and ws are one endpoint: the servlet takes the WebSocket upgrade on its path.
+			// http and ws are one endpoint: the host takes the WebSocket upgrade on its path.
 			properties.put("spring.acp.agent.transport.type", "ws".equals(transport) ? "websocket" : "http");
 			properties.put("spring.acp.agent.transport.http.path", "/acp");
 		}
@@ -74,7 +79,7 @@ private static String value(String[] args, int i) {
 
 	private static void usage(String problem) {
 		System.err.println(problem);
-		System.err.println("usage: agent.sh --transport stdio | --transport http|ws --port <port>");
+		System.err.println("usage: agent.sh [--web servlet|reactive] --transport stdio | --transport http|ws --port <port>");
 		System.exit(2);
 	}