Add unit tests for CompilerUtils and Java file management

Author: peter-lawrey

README.adoc

@@ -2,6 +2,7 @@
 Chronicle Software
 :css-signature: demo
 :toc: macro
+:sectnums:
 :source-highlighter: rouge
 
 image:https://maven-badges.herokuapp.com/maven-central/net.openhft/compiler/badge.svg[]
@@ -13,7 +14,7 @@ toc::[]
 
 This library lets you feed _plain Java source as a_ `String`, compile it in-memory and immediately load the resulting `Class<?>` - perfect for hot-swapping logic while the JVM is still running.
 
-== 1 Quick-Start
+== Quick-Start
 
 [source,xml,subs=+quotes]
 ----
@@ -50,9 +51,9 @@ Class<?> clazz = CompilerUtils.CACHED_COMPILER.loadFromJava(className, src);
 ((Runnable) clazz.getDeclaredConstructor().newInstance()).run();
 ----
 
-== 2 Installation
+== Installation
 
-* Requires a **full JDK** (8, 11, 17 or 21 LTS), _not_ a slim JRE.
+* Requires a *full JDK* (8, 11, 17 or 21 LTS), _not_ a slim JRE.
 * On Java 11 + supply these flags (copy-paste safe):
 
 [source,bash]
@@ -65,7 +66,7 @@ Class<?> clazz = CompilerUtils.CACHED_COMPILER.loadFromJava(className, src);
 ** unpack Chronicle jars:
 `bootJar { requiresUnpack("**/chronicle-*.jar") }`
 
-== 3 Feature Highlights
+== Feature Highlights
 
 |===
 | Feature | Benefit
@@ -86,39 +87,43 @@ Class<?> clazz = CompilerUtils.CACHED_COMPILER.loadFromJava(className, src);
 | Build helper hierarchy in a single call
 |===
 
-== 4 Advanced Usage & Patterns
+== Advanced Usage & Patterns
 
-* Hot-swappable *strategy interface* for trading engines
+* Hot-swappable _strategy interface_ for trading engines
 ** Rule-engine: compile business rules implementing `Rule`
 *** Supports validator hook to vet user code
 ** Replace reflection: generate POJO accessors, 10 x faster
 ** Off-heap accessors with Chronicle Bytes / Map
 
-== 5 Operational Notes
+== Operational Notes
 
 * Compile on a background thread at start-up; then swap instances.
 ** Re-use class names _or_ child classloaders to control Metaspace.
 *** Use `CompilerUtils.DEBUGGING = true` during dev; remember to prune artefacts.
 ** SLF4J categories: `net.openhft.compiler` (INFO), compilation errors at ERROR.
 ** Micrometer timers/counters: `compiler.compiles`, `compiler.failures`.
 
-== 6 FAQ / Troubleshooting
+== Documentation & Requirements
 
-* *`ToolProvider.getSystemJavaCompiler() == null`*
+* link:src/main/docs/project-requirements.adoc[Project requirements] outline functional, non-functional, and compliance obligations.
+
+== FAQ / Troubleshooting
+
+* _`ToolProvider.getSystemJavaCompiler() == null`_
 * You are running on a JRE; use a JDK.
-* *`ClassNotFoundException: com.sun.tools.javac.api.JavacTool`*
+* _`ClassNotFoundException: com.sun.tools.javac.api.JavacTool`_
 * tools.jar is required on JDK <= 8. Newer JDKs need the `--add-exports` and `--add-opens` flags.
 * Classes never unload
 * Generate with a unique `ClassLoader` per version so classes can unload; each loader uses Metaspace.
 * Illegal-reflective-access warning
 * Add the `--add-opens` & `--add-exports` flags shown above.
 
-== 7 CI / Build & Test
+== CI / Build & Test
 
 * GitHub Actions workflow runs `mvn verify`, unit & race-condition tests.
 ** Code-coverage report published to SonarCloud badge above.
 
-== 8 Contributing & License
+== Contributing & License
 
 * Fork -> feature branch -> PR; run `mvn spotless:apply` before pushing.
-** All code under the *Apache License 2.0* - see `LICENSE`.
+** All code under the _Apache License 2.0_ - see `LICENSE`.

src/test/java/net/openhft/compiler/AiRuntimeGuardrailsTest.java

@@ -0,0 +1,279 @@
+/*
+ * Copyright 2013-2025 chronicle.software; SPDX-License-Identifier: Apache-2.0
+ */
+package net.openhft.compiler;
+
+import org.junit.Test;
+
+import java.util.*;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.junit.Assert.*;
+
+public class AiRuntimeGuardrailsTest {
+
+    @Test
+    public void validatorStopsCompilationAndRecordsFailure() {
+        AtomicInteger compileInvocations = new AtomicInteger();
+        TelemetryProbe telemetry = new TelemetryProbe();
+        GuardrailedCompilerPipeline pipeline = new GuardrailedCompilerPipeline(
+                Arrays.asList(
+                        source -> {
+                            // basic guard: ban java.lang.System exit calls
+                            if (source.contains("System.exit")) {
+                                throw new ValidationException("System.exit is not allowed");
+                            }
+                        },
+                        source -> {
+                            if (source.contains("java.io.File")) {
+                                throw new ValidationException("File IO is not permitted");
+                            }
+                        }
+                ),
+                telemetry,
+                (className, source) -> {
+                    compileInvocations.incrementAndGet();
+                    try {
+                        return Class.forName("java.lang.Object");
+                    } catch (ClassNotFoundException e) {
+                        throw new AssertionError("JDK runtime missing java.lang.Object", e);
+                    }
+                }
+        );
+
+        try {
+            pipeline.compile("agent-A", "BadClass", "class BadClass { void x() { System.exit(0); } }");
+            fail("Expected validation failure");
+        } catch (ValidationException expected) {
+            // expected
+        } catch (Exception unexpected) {
+            fail("Unexpected checked exception: " + unexpected.getMessage());
+        }
+
+        assertEquals("Compilation must not run after validation rejection", 0, compileInvocations.get());
+        assertEquals(1, telemetry.compileAttempts("agent-A"));
+        assertEquals(1, telemetry.validationFailures("agent-A"));
+        assertEquals(0, telemetry.successes("agent-A"));
+        assertEquals(0, telemetry.compileFailures("agent-A"));
+        assertFalse("Latency should not be recorded for rejected source", telemetry.hasLatency("agent-A"));
+    }
+
+    @Test
+    public void successfulCompilationRecordsMetrics() throws Exception {
+        TelemetryProbe telemetry = new TelemetryProbe();
+        GuardrailedCompilerPipeline pipeline = new GuardrailedCompilerPipeline(
+                Collections.singletonList(source -> {
+                    if (!source.contains("class")) {
+                        throw new ValidationException("Missing class keyword");
+                    }
+                }),
+                telemetry,
+                new CachedCompilerInvoker()
+        );
+
+        Class<?> clazz = pipeline.compile("agent-B", "OkClass",
+                "public class OkClass { public int add(int a, int b) { return a + b; } }");
+
+        assertEquals("agent-B should see exactly one attempt", 1, telemetry.compileAttempts("agent-B"));
+        assertEquals(0, telemetry.validationFailures("agent-B"));
+        assertEquals(1, telemetry.successes("agent-B"));
+        assertEquals(0, telemetry.compileFailures("agent-B"));
+        assertTrue("Latency must be captured for successful compilation", telemetry.hasLatency("agent-B"));
+
+        Object instance = clazz.getDeclaredConstructor().newInstance();
+        int sum = (int) clazz.getMethod("add", int.class, int.class).invoke(instance, 2, 3);
+        assertEquals(5, sum);
+    }
+
+    @Test
+    public void cacheHitDoesNotRecompileButRecordsMetric() throws Exception {
+        AtomicInteger rawCompileCount = new AtomicInteger();
+        TelemetryProbe telemetry = new TelemetryProbe();
+        GuardrailedCompilerPipeline pipeline = new GuardrailedCompilerPipeline(
+                Collections.emptyList(),
+                telemetry,
+                (className, source) -> {
+                    rawCompileCount.incrementAndGet();
+                    return CompilerUtils.CACHED_COMPILER.loadFromJava(className, source);
+                }
+        );
+
+        String source = "public class CacheCandidate { public String id() { return \"ok\"; } }";
+        Class<?> first = pipeline.compile("agent-C", "CacheCandidate", source);
+        Class<?> second = pipeline.compile("agent-C", "CacheCandidate", source);
+
+        assertEquals("Underlying compiler should only run once thanks to caching", 1, rawCompileCount.get());
+        assertEquals(2, telemetry.compileAttempts("agent-C"));
+        assertEquals(0, telemetry.validationFailures("agent-C"));
+        assertEquals(1, telemetry.successes("agent-C"));
+        assertEquals(0, telemetry.compileFailures("agent-C"));
+        assertEquals("Cache hit count should be tracked", 1, telemetry.cacheHits("agent-C"));
+        assertTrue(first == second);
+    }
+
+    @Test
+    public void compilerFailureRecordedSeparately() {
+        TelemetryProbe telemetry = new TelemetryProbe();
+        GuardrailedCompilerPipeline pipeline = new GuardrailedCompilerPipeline(
+                Collections.singletonList(source -> {
+                    if (source.contains("forbidden")) {
+                        throw new ValidationException("Forbidden token");
+                    }
+                }),
+                telemetry,
+                (className, source) -> {
+                    throw new ClassNotFoundException("Simulated compiler failure");
+                }
+        );
+
+        try {
+            pipeline.compile("agent-D", "Broken", "public class Broken { }");
+            fail("Expected compiler failure");
+        } catch (ClassNotFoundException expected) {
+            // expected
+        } catch (Exception unexpected) {
+            fail("Unexpected exception: " + unexpected.getMessage());
+        }
+
+        assertEquals(1, telemetry.compileAttempts("agent-D"));
+        assertEquals(0, telemetry.validationFailures("agent-D"));
+        assertEquals(0, telemetry.successes("agent-D"));
+        assertEquals(1, telemetry.compileFailures("agent-D"));
+        assertFalse("Failure should not record cache hits", telemetry.hasCacheHits("agent-D"));
+    }
+
+    private static final class GuardrailedCompilerPipeline {
+        private final List<SourceValidator> validators;
+        private final TelemetryProbe telemetry;
+        private final CompilerInvoker compilerInvoker;
+        private final Map<String, Class<?>> cache = new ConcurrentHashMap<>();
+
+        GuardrailedCompilerPipeline(List<SourceValidator> validators,
+                                    TelemetryProbe telemetry,
+                                    CompilerInvoker compilerInvoker) {
+            this.validators = new ArrayList<>(validators);
+            this.telemetry = telemetry;
+            this.compilerInvoker = compilerInvoker;
+        }
+
+        Class<?> compile(String agentId, String className, String source) throws Exception {
+            telemetry.recordAttempt(agentId);
+            for (SourceValidator validator : validators) {
+                try {
+                    validator.validate(source);
+                } catch (ValidationException e) {
+                    telemetry.recordValidationFailure(agentId);
+                    throw e;
+                }
+            }
+
+            Class<?> cached = cache.get(className);
+            if (cached != null) {
+                telemetry.recordCacheHit(agentId);
+                return cached;
+            }
+
+            long start = System.nanoTime();
+            try {
+                Class<?> compiled = compilerInvoker.compile(className, source);
+                cache.put(className, compiled);
+                telemetry.recordSuccess(agentId, System.nanoTime() - start);
+                return compiled;
+            } catch (ClassNotFoundException | RuntimeException e) {
+                telemetry.recordCompileFailure(agentId);
+                throw e;
+            }
+        }
+    }
+
+    @FunctionalInterface
+    private interface CompilerInvoker {
+        Class<?> compile(String className, String source) throws Exception;
+    }
+
+    @FunctionalInterface
+    private interface SourceValidator {
+        void validate(String source);
+    }
+
+    private static final class ValidationException extends RuntimeException {
+        ValidationException(String message) {
+            super(message);
+        }
+    }
+
+    private static final class TelemetryProbe {
+        private final Map<String, AtomicInteger> attempts = new HashMap<>();
+        private final Map<String, AtomicInteger> successes = new HashMap<>();
+        private final Map<String, AtomicInteger> validationFailures = new HashMap<>();
+        private final Map<String, AtomicInteger> compileFailures = new HashMap<>();
+        private final Map<String, AtomicInteger> cacheHits = new HashMap<>();
+        private final Map<String, Long> latencyNanos = new HashMap<>();
+
+        void recordAttempt(String agentId) {
+            increment(attempts, agentId);
+        }
+
+        void recordSuccess(String agentId, long durationNanos) {
+            increment(successes, agentId);
+            latencyNanos.put(agentId, durationNanos);
+        }
+
+        void recordValidationFailure(String agentId) {
+            increment(validationFailures, agentId);
+        }
+
+        void recordCompileFailure(String agentId) {
+            increment(compileFailures, agentId);
+        }
+
+        void recordCacheHit(String agentId) {
+            increment(cacheHits, agentId);
+        }
+
+        int compileAttempts(String agentId) {
+            return read(attempts, agentId);
+        }
+
+        int successes(String agentId) {
+            return read(successes, agentId);
+        }
+
+        int validationFailures(String agentId) {
+            return read(validationFailures, agentId);
+        }
+
+        int compileFailures(String agentId) {
+            return read(compileFailures, agentId);
+        }
+
+        int cacheHits(String agentId) {
+            return read(cacheHits, agentId);
+        }
+
+        boolean hasLatency(String agentId) {
+            return latencyNanos.containsKey(agentId) && latencyNanos.get(agentId) > 0;
+        }
+
+        boolean hasCacheHits(String agentId) {
+            return cacheHits.containsKey(agentId) && cacheHits.get(agentId).get() > 0;
+        }
+
+        private void increment(Map<String, AtomicInteger> map, String agentId) {
+            map.computeIfAbsent(agentId, key -> new AtomicInteger()).incrementAndGet();
+        }
+
+        private int read(Map<String, AtomicInteger> map, String agentId) {
+            AtomicInteger value = map.get(agentId);
+            return value == null ? 0 : value.get();
+        }
+    }
+
+    private static final class CachedCompilerInvoker implements CompilerInvoker {
+        @Override
+        public Class<?> compile(String className, String source) throws Exception {
+            return CompilerUtils.CACHED_COMPILER.loadFromJava(className, source);
+        }
+    }
+}