Merge pull request #6 from lucee/fix/agent-warmup-skip

agent: skip init on warmup, mark step-handler daemon; add jdwp timeout=10000 to CI

Author: zspitzer

.github/workflows/main.yml

@@ -523,7 +523,7 @@ jobs:
           echo "export LUCEE_DAP_SECRET=testing" >> debuggee/bin/setenv.sh
           echo "export LUCEE_LOGGING_FORCE_LEVEL=trace" >> debuggee/bin/setenv.sh
           echo "export LUCEE_DAP_DEBUG=true" >> debuggee/bin/setenv.sh
-          echo "export CATALINA_OPTS=\"\$CATALINA_OPTS -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=localhost:9999\"" >> debuggee/bin/setenv.sh
+          echo "export CATALINA_OPTS=\"\$CATALINA_OPTS -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=localhost:9999,timeout=10000\"" >> debuggee/bin/setenv.sh
           echo "export CATALINA_OPTS=\"\$CATALINA_OPTS -javaagent:\$CATALINA_HOME/$AGENT_JAR_NAME=jdwpHost=localhost,jdwpPort=9999,debugHost=0.0.0.0,debugPort=10000,jarPath=\$CATALINA_HOME/$AGENT_JAR_NAME\"" >> debuggee/bin/setenv.sh
           chmod +x debuggee/bin/setenv.sh
 

JAVA_AGENT.md

@@ -35,6 +35,7 @@ Configures JDWP, the lower-level Java debugging protocol that the debugger agent
 | `server` | `y` | Use verbatim |
 | `suspend` | `n` | Use verbatim |
 | `address` | `localhost:9999` | Change only if port 9999 is in use |
+| `timeout` | `10000` | Recommended. Prevents JDWP from hanging at JVM shutdown if no debugger was ever connected (e.g. after a Lucee warmup run). |
 
 **Note:** The VS Code debugger connects to the debugger agent, not JDWP directly, so these settings rarely need customising.
 
@@ -99,14 +100,14 @@ For agent mode, you don't need the `secret` field - that's only for native exten
 
 ```bash
 #!/bin/bash
-CATALINA_OPTS="$CATALINA_OPTS -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=localhost:9999"
+CATALINA_OPTS="$CATALINA_OPTS -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=localhost:9999,timeout=10000"
 CATALINA_OPTS="$CATALINA_OPTS -javaagent:/opt/lucee/debugger/debugger-agent.jar=jdwpHost=localhost,jdwpPort=9999,debugHost=0.0.0.0,debugPort=10000,jarPath=/opt/lucee/debugger/debugger-agent.jar"
 ```
 
 ### Windows (setenv.bat)
 
 ```batch
-set CATALINA_OPTS=%CATALINA_OPTS% -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=localhost:9999
+set CATALINA_OPTS=%CATALINA_OPTS% -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=localhost:9999,timeout=10000
 set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:C:\lucee\debugger\debugger-agent.jar=jdwpHost=localhost,jdwpPort=9999,debugHost=0.0.0.0,debugPort=10000,jarPath=C:\lucee\debugger\debugger-agent.jar
 ```
 
@@ -125,3 +126,9 @@ You're running a JRE instead of a JDK. Install a full JDK.
 ### Breakpoints not binding
 
 Use the VS Code command palette and run "luceedebug: show class and breakpoint info" to see what's happening.
+
+### Lucee warmup (`LUCEE_ENABLE_WARMUP`)
+
+The agent automatically detects the `LUCEE_ENABLE_WARMUP` environment variable and skips initialization. No class instrumentation or DAP server setup happens during a warmup run. The real server start that follows will instrument classes normally as they are loaded.
+
+This also avoids JDWP shutdown hangs during warmup — pair with `timeout=10000` in your JDWP args for reliable warmup exits.

source/java/src/org/lucee/extension/debugger/Agent.java

@@ -265,6 +265,11 @@ public static void premain(String argString, Instrumentation inst) throws Throwa
         // TODO: clarify the exact failure case we are attempting to workaround here.
         System.out.println("[luceedebug] version " + Version.VERSION);
 
+        if (System.getenv("LUCEE_ENABLE_WARMUP") != null) {
+            System.out.println("[luceedebug] warmup mode detected, skipping initialization");
+            return;
+        }
+
         try (var jarFile = new JarFile(parsedArgs.jarPath)) {
             inst.appendToSystemClassLoaderSearch(jarFile);
             var classInjections = jarFile

source/java/src/org/lucee/extension/debugger/coreinject/LuceeVm.java

@@ -177,7 +177,11 @@ static BpLineAndId[] getLineInfo(Collection<ReplayableCfBreakpointRequest> vs) {
     }
 
     private final ThreadMap threadMap_ = new ThreadMap();
-    private final ExecutorService stepHandlerExecutor = Executors.newSingleThreadExecutor();
+    private final ExecutorService stepHandlerExecutor = Executors.newSingleThreadExecutor(r -> {
+        var t = new Thread(r, "luceedebug-step-handler");
+        t.setDaemon(true);
+        return t;
+    });
     private final ConcurrentHashMap<CanonicalServerAbsPath, Set<ReplayableCfBreakpointRequest>> replayableBreakpointRequestsByAbsPath_ = new ConcurrentHashMap<>();
 
     /**