Conversation
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Upgrade pragmatica-lite to 0.9.3 - Add ObservabilityRegistry with Micrometer/Prometheus - Add AetherMetrics for pre-configured operation metrics - Add GET /metrics/prometheus endpoint for scraping - Include JVM metrics (memory, GC, threads, classloaders) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
… 0.9.3 compatibility 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Also change RabiaNodeNettyIT base port to 13040 to reduce test flakiness 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Tests pass individually but fail intermittently when run together due to resource contention (TCP ports, executor shutdown timing). Disabled tests: - RabiaNodeNettyIT - AetherNodeIT - ClusterFailoverIT - MessageSemanticsIT 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughRelease 0.6.4 introduces rolling update support with state machines and weighted routing, E2E testing infrastructure using Testcontainers, Docker containerization for cluster deployment, observability metrics via Micrometer, and CI/CD enhancements for automated testing and image building. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/guide/getting-started.md (1)
98-107: Update core dependency version in documentation.The
slice-apiversion was updated to0.6.4, but theorg.pragmatica-lite:coredependency still shows0.9.0. The root POM now usespragmatica.version0.9.3. Consider updating this to match.🔎 Proposed fix
<dependency> <groupId>org.pragmatica-lite</groupId> <artifactId>core</artifactId> - <version>0.9.0</version> + <version>0.9.3</version> </dependency>
🧹 Nitpick comments (28)
node/src/test/java/org/pragmatica/aether/node/ClusterFailoverIT.java (1)
68-68: Consider removing unused ExecutorService.The
executorfield is created insetUpand cleaned up intearDown, but it's never actually used by any test methods. ThestartContinuousRequestsmethod creates regularThreadinstances directly (line 473) rather than submitting tasks to the executor.🔎 Proposed cleanup
Remove the unused executor field and its lifecycle management:
- private ExecutorService executor; @BeforeEach void setUp() throws InterruptedException { - executor = Executors.newVirtualThreadPerTaskExecutor(); startNodes(ALL_NODES.subList(0, CLUSTER_SIZE)); // Allow cluster to stabilize Thread.sleep(1000); } @AfterEach void tearDown() throws InterruptedException { - executor.shutdownNow(); - executor.awaitTermination(5, TimeUnit.SECONDS); - for (var node : nodes) {Also applies to: 76-77
cli/src/main/java/org/pragmatica/aether/cli/AetherCli.java (1)
492-501: Consider JSON escaping for user-provided values.String concatenation for JSON construction is vulnerable to malformed/injected input if
artifactBase,version, orcleanupPolicycontain quotes or special characters. While this matches existing commands (e.g.,DeployCommand), consider using a JSON library or escaping values.🔎 Proposed fix using minimal escaping
+ private String escapeJson(String value) { + return value.replace("\\", "\\\\") + .replace("\"", "\\\"") + .replace("\n", "\\n") + .replace("\r", "\\r") + .replace("\t", "\\t"); + } + @Override public Integer call() { - var body = "{\"artifactBase\":\"" + artifactBase + "\"," + "\"version\":\"" + version + "\"," - + "\"instances\":" + instances + "," + "\"maxErrorRate\":" + errorRate + "," - + "\"maxLatencyMs\":" + latencyMs + "," + "\"requireManualApproval\":" + manualApproval - + "," + "\"cleanupPolicy\":\"" + cleanupPolicy + "\"}"; + var body = "{\"artifactBase\":\"" + escapeJson(artifactBase) + "\"," + + "\"version\":\"" + escapeJson(version) + "\"," + + "\"instances\":" + instances + "," + "\"maxErrorRate\":" + errorRate + "," + + "\"maxLatencyMs\":" + latencyMs + "," + "\"requireManualApproval\":" + manualApproval + + ",\"cleanupPolicy\":\"" + escapeJson(cleanupPolicy) + "\"}"; var response = updateParent.parent.postToNode("/rolling-update/start", body);cluster/src/test/java/org/pragmatica/node/RabiaNodeNettyIT.java (1)
6-6: Remove unused import.The
org.junit.jupiter.api.Tagimport is not used anywhere in the test class.🔎 Proposed fix
-import org.junit.jupiter.api.Tag;e2e-tests/pom.xml (2)
16-20: Minor version inconsistency with root POM.
awaitility.versionis set to4.2.2here, but the root POM defines it as4.2.1. Consider aligning versions or inheriting from the parent'sdependencyManagementto avoid potential conflicts.
89-110: Failsafe plugin version override.This module uses
maven-failsafe-pluginversion3.5.2, while the root POM'spluginManagementdeclares3.5.1. If this is intentional (e.g., for a specific bug fix), consider documenting the reason or updating the root POM to maintain consistency..github/workflows/ci.yml (1)
123-125: Quote the command substitution to prevent word splitting.The static analysis tool flagged SC2086. If
project.versioncontains spaces or special characters, the unquoted substitution could cause issues.🔎 Proposed fix
- name: Extract version id: version - run: echo "VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)" >> $GITHUB_OUTPUT + run: echo "VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)" >> "$GITHUB_OUTPUT"node/src/main/java/org/pragmatica/aether/update/HealthThresholds.java (1)
38-48: Consider returningResultinstead of throwing exceptions.Per coding guidelines, failures should flow through
Resultrather than throwing business exceptions. While construction validation is borderline, usingResult.lift()or returningResult<HealthThresholds>would align with the project's error-handling philosophy.🔎 Proposed refactor using Result
+import org.pragmatica.lang.Result; +import static org.pragmatica.lang.Result.success; +import static org.pragmatica.lang.Result.failure; - public static HealthThresholds healthThresholds(double maxErrorRate, - long maxLatencyMs, - boolean requireManualApproval) { - if (maxErrorRate < 0.0 || maxErrorRate > 1.0) { - throw new IllegalArgumentException("Error rate must be between 0.0 and 1.0"); - } - if (maxLatencyMs < 0) { - throw new IllegalArgumentException("Latency must be non-negative"); - } - return new HealthThresholds(maxErrorRate, maxLatencyMs, requireManualApproval); - } + public static Result<HealthThresholds> healthThresholds(double maxErrorRate, + long maxLatencyMs, + boolean requireManualApproval) { + if (maxErrorRate < 0.0 || maxErrorRate > 1.0) { + return failure(ValidationError.invalidErrorRate(maxErrorRate)); + } + if (maxLatencyMs < 0) { + return failure(ValidationError.invalidLatency(maxLatencyMs)); + } + return success(new HealthThresholds(maxErrorRate, maxLatencyMs, requireManualApproval)); + }Based on coding guidelines: "Never throw business exceptions - all failures flow through
ResultorPromise".e2e-tests/src/test/java/org/pragmatica/aether/e2e/ChaosE2ETest.java (1)
167-168: Consider verifying thread termination after join timeout.If threads don't terminate within 5 seconds, they continue running after the test completes. Consider checking
isAlive()or interrupting threads after the join timeout.🔎 Proposed enhancement
chaosThread.join(5000); opsThread.join(5000); + +if (chaosThread.isAlive()) chaosThread.interrupt(); +if (opsThread.isAlive()) opsThread.interrupt();docker/aether-forge/Dockerfile (1)
8-8: Consider parameterizing the version label.The version is hardcoded, which requires manual updates for each release. Consider using a build argument for easier maintenance.
🔎 Proposed refactor
+ARG VERSION=0.6.4 + FROM eclipse-temurin:25-alpine LABEL org.opencontainers.image.title="Aether Forge" LABEL org.opencontainers.image.description="Aether cluster testing simulator with visual dashboard" -LABEL org.opencontainers.image.version="0.6.4" +LABEL org.opencontainers.image.version="${VERSION}" LABEL org.opencontainers.image.source="https://github.com/siy/aether"Then build with:
docker build --build-arg VERSION=0.6.4 -t aether-forge:0.6.4 .e2e-tests/src/test/java/org/pragmatica/aether/e2e/SliceDeploymentE2ETest.java (2)
60-76: Consider verifying actual instance distribution.The test confirms that all nodes report the slice artifact but doesn't verify that 3 distinct instances were created or how they're distributed across nodes. While this may be acceptable for initial E2E coverage, consider enhancing the test to verify actual instance count and distribution for more robust validation.
151-158: Consider parsing JSON responses instead of string matching.The helper uses simple string containment checks (
slices.contains(artifact) && slices.contains("ACTIVE")), which is brittle. For example, "ACTIVE" could appear in unrelated contexts, or the artifact string might be a substring of a different artifact name.Consider using a JSON parser (e.g., Jackson, Gson, or simple
JsonParser) to extract structured data and verify the slice state properly. This would make tests more robust and easier to maintain as the API evolves.node/src/main/java/org/pragmatica/aether/api/ManagementServer.java (1)
520-555: Complete the rolling update handler implementations.All rolling update endpoints currently return
"not_implemented"placeholder responses. While the routing and endpoint structure is in place, the handlers need integration withRollingUpdateManagerto provide actual functionality.The infrastructure is well-structured with proper endpoint routing and parameter extraction. Would you like me to help generate the complete implementations that integrate with
RollingUpdateManagerand follow the state machine flow defined in the architecture docs? I can also help ensure proper error handling usingPromise<T>andResult<T>patterns per the coding guidelines.slice/src/main/java/org/pragmatica/aether/artifact/ArtifactBase.java (1)
17-17: Minor formatting: missing space in field declaration.🔎 Suggested fix
- private static final Fn1<Cause, String>INVALID_FORMAT = Causes.forOneValue("Invalid artifact base format {}"); + private static final Fn1<Cause, String> INVALID_FORMAT = Causes.forOneValue("Invalid artifact base format {}");node/src/main/java/org/pragmatica/aether/update/VersionRouting.java (3)
35-43: Factory method throws exceptions instead of returning Result.Per coding guidelines: "Never throw business exceptions - all failures flow through
ResultorPromiseas typedCausesealed interfaces." Consider returningResult<VersionRouting>instead of throwingIllegalArgumentException.However, if this is intentional for CLI/API boundary validation where exceptions are caught and converted, this may be acceptable.
🔎 Result-based alternative
public static Result<VersionRouting> versionRouting(int newWeight, int oldWeight) { if (newWeight < 0 || oldWeight < 0) { return NEGATIVE_WEIGHT_ERROR.result(); } if (newWeight == 0 && oldWeight == 0) { return ZERO_WEIGHTS_ERROR.result(); } return Result.success(new VersionRouting(newWeight, oldWeight)); }
52-63: Minor formatting issue and same exception concern.Line 57 is missing a space:
try{→try {.Same consideration as the factory method regarding exception throwing vs
Result.🔎 Formatting fix
- try{ + try {
105-121: ConsiderOptioninstead of nullable return.Returning
nullfor unsatisfiable routing deviates from the project's functional style. ConsiderOption<int[]>or a dedicated record type.Also, array formatting on lines 119-120 is inconsistent:
🔎 Suggested improvements
- public int[] scaleToInstances(int newInstances, int oldInstances) { + public Option<int[]> scaleToInstances(int newInstances, int oldInstances) { if (isAllOld()) { - return new int[] {0, oldInstances}; + return Option.option(new int[]{0, oldInstances}); } if (isAllNew()) { - return new int[] {newInstances, 0}; + return Option.option(new int[]{newInstances, 0}); } // Calculate maximum scale factor int maxNewScale = newInstances / newWeight; int maxOldScale = oldInstances / oldWeight; int scaleFactor = Math.min(maxNewScale, maxOldScale); if (scaleFactor < 1) { - return null; + return Option.none(); } - return new int[] {scaleFactor * newWeight, - scaleFactor * oldWeight}; + return Option.option(new int[]{scaleFactor * newWeight, scaleFactor * oldWeight}); }node/src/main/java/org/pragmatica/aether/endpoint/EndpointRegistry.java (1)
175-235: Weighted routing implementation is correct with good edge-case handling.The algorithm properly:
- Groups endpoints by version
- Falls back gracefully when routing is all-old/all-new or one version has no endpoints
- Handles unsatisfiable ratios by falling back to old version
- Uses weighted round-robin with correct position calculation
Two minor formatting issues:
🔎 Formatting fixes
- }else { + } else {(Line 230)
If
VersionRouting.scaleToInstances()is refactored to returnOption, this null check would become pattern matching.slice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherKey.java (1)
305-322: Naming inconsistency in parsing method.Other key types use
keyType(String key)for parsing (e.g.,BlueprintKey.blueprintKey(String key)), butRollingUpdateKeyusesparse(String key). Consider renaming for consistency:🔎 Suggested rename
- public static Result<RollingUpdateKey> parse(String key) { + public static Result<RollingUpdateKey> rollingUpdateKey(String key) {This is minor since the factory method
rollingUpdateKey(String updateId)serves a different purpose (creation from ID vs parsing from key string).e2e-tests/src/test/java/org/pragmatica/aether/e2e/ClusterFormationE2ETest.java (2)
77-79: Prefer method reference over lambda.Per coding guidelines: "Prefer method references over lambdas when the lambda only calls a single method."
🔎 Suggested fix
- var statuses = cluster.nodes().stream() - .map(node -> node.getStatus()) - .toList(); + var statuses = cluster.nodes().stream() + .map(AetherNodeContainer::getStatus) + .toList();
88-97: Metrics test is appropriate but could be more specific.The test verifies metrics endpoint returns without error. Consider adding assertions for expected metric names (e.g., JVM metrics, cluster metrics) to make the test more robust.
Optional: The repeated
cluster.start(); cluster.awaitQuorum();pattern in each test could be moved to@BeforeEachfor DRYer tests.node/src/main/java/org/pragmatica/aether/update/RollingUpdate.java (2)
54-74: Consider factory naming convention.Per coding guidelines, factory methods should follow
TypeName.typeName(...)pattern. Consider renaming torollingUpdate(...)for consistency.🔎 Suggested rename
- public static RollingUpdate create(String updateId, + public static RollingUpdate rollingUpdate(String updateId,
83-101: Exception thrown violates Result-based error handling guideline.Per coding guidelines: "Never throw business exceptions - all failures flow through
ResultorPromise." TheIllegalStateExceptionhere breaks this pattern. Consider returningResult<RollingUpdate>instead.🔎 Proposed refactor using Result
+import org.pragmatica.lang.Result; + - public RollingUpdate transitionTo(RollingUpdateState newState) { - if (!state.validTransitions() - .contains(newState)) { - throw new IllegalStateException( - "Invalid transition from " + state + " to " + newState); - } - return new RollingUpdate( + public Result<RollingUpdate> transitionTo(RollingUpdateState newState) { + if (!state.validTransitions().contains(newState)) { + return Result.failure(new RollingUpdateError.InvalidStateTransition(state, newState)); + } + return Result.success(new RollingUpdate( updateId, artifactBase, oldVersion, newVersion, newState, routing, thresholds, cleanupPolicy, newInstances, createdAt, - System.currentTimeMillis()); + System.currentTimeMillis())); }node/src/main/java/org/pragmatica/aether/metrics/observability/ObservabilityRegistry.java (1)
126-133: Prefer method reference over lambda.Per coding guidelines: "Prefer method references over lambdas when the lambda only calls a single method."
🔎 Suggested simplification
@Override public Gauge gauge(String name, Supplier<Number> supplier, String... tags) { - return Gauge.builder(name, - () -> supplier.get() - .doubleValue()) + return Gauge.builder(name, supplier, number -> number.doubleValue()) .tags(tags) .register(prometheusRegistry); }Note: The Micrometer
Gauge.builderaccepts a state object and a function, so this would requiresupplieras the state object if the API supports it. Alternatively, you could extract the lambda to a helper if the current form is clearer.e2e-tests/src/test/java/org/pragmatica/aether/e2e/NodeFailureE2ETest.java (1)
76-95: Consider adding assertion message for leader failure test.If
cluster.leader()returns empty initially (e.g., cluster not yet stabilized), theorElseThrow()will throw a genericNoSuchElementException. Consider adding a descriptive message.🔎 Suggested improvement
- var originalLeader = cluster.leader().orElseThrow(); + var originalLeader = cluster.leader() + .orElseThrow(() -> new AssertionError("Expected leader to be present after quorum"));e2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherCluster.java (2)
43-46: Unused fieldprojectRoot.The field is stored but never accessed after the constructor. Consider removing it or documenting its intended future use.
🔎 Suggested fix
private final List<AetherNodeContainer> nodes; private final Network network; - private final Path projectRoot; private final Map<String, AetherNodeContainer> nodeMap; private AetherCluster(int size, Path projectRoot) { - this.projectRoot = projectRoot; this.network = Network.newNetwork();
259-269: Fragile JSON parsing and variable shadowing.
- Variable shadowing: Local variable
nodesshadows the fieldthis.nodes, which can cause confusion.- Fragile parsing: Counting
{characters is unreliable if node objects contain nested objects.Consider using a proper JSON parser or renaming the local variable.
🔎 Suggested improvements
private int activeNodeCount() { try { - var nodes = anyNode().getNodes(); + var nodesJson = anyNode().getNodes(); // Count node entries in JSON array - return (int) nodes.chars() - .filter(ch -> ch == '{') - .count(); + // Note: This assumes flat node objects without nested braces + return (int) nodesJson.chars() + .filter(ch -> ch == '{') + .count(); } catch (Exception e) { return 0; } }For more robust parsing, consider using a JSON library like Jackson's
ObjectMapperto parse the array properly.node/src/main/java/org/pragmatica/aether/metrics/observability/AetherMetrics.java (1)
105-118: Inconsistent metric naming convention.Rolling update metrics use underscores (
aether.rolling_update.started) while other metrics use dots (aether.slice.invocation). Consider aligning to a single convention.🔎 Suggested naming alignment
@Override public Counter rollingUpdateStarted() { - return registry.counter("aether.rolling_update.started"); + return registry.counter("aether.rolling.update.started"); } @Override public Counter rollingUpdateCompleted() { - return registry.counter("aether.rolling_update.completed"); + return registry.counter("aether.rolling.update.completed"); } @Override public Counter rollingUpdateRolledBack() { - return registry.counter("aether.rolling_update.rolled_back"); + return registry.counter("aether.rolling.update.rolledback"); }e2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherNodeContainer.java (1)
121-123: Consider defensive access to network aliases.While
getNetworkAliases().getFirst()works currently (network alias is set in line 64), this creates a fragile dependency on factory method implementation. If a future factory variant skipswithNetworkAliases(), this will throwNoSuchElementException.🔎 Safer access pattern
public String clusterAddress() { - return nodeId + ":" + getNetworkAliases().getFirst() + ":" + CLUSTER_PORT; + var aliases = getNetworkAliases(); + if (aliases.isEmpty()) { + throw new IllegalStateException("Container must be configured with a network before accessing cluster address"); + } + return nodeId + ":" + aliases.getFirst() + ":" + CLUSTER_PORT; }
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (61)
.github/workflows/ci.ymlCHANGELOG.mdCLAUDE.mdcli/pom.xmlcli/src/main/java/org/pragmatica/aether/cli/AetherCli.javacluster/pom.xmlcluster/src/main/java/org/pragmatica/cluster/node/rabia/CustomClasses.javacluster/src/main/java/org/pragmatica/cluster/node/rabia/RabiaNode.javacluster/src/test/java/org/pragmatica/cluster/consensus/rabia/MessageSemanticsIT.javacluster/src/test/java/org/pragmatica/cluster/consensus/rabia/infrastructure/TestCluster.javacluster/src/test/java/org/pragmatica/node/RabiaNodeNettyIT.javadocker/aether-forge/Dockerfiledocker/aether-node/Dockerfiledocker/docker-compose.ymldocs/architecture-overview.mddocs/archive/aether-high-level-overview.mddocs/development-priorities.mddocs/guide/cli-reference.mddocs/guide/getting-started.mddocs/guide/migration-guide.mddocs/jbct-cli-slice-support-task.mddocs/typed-slice-api-design.mde2e-tests/pom.xmle2e-tests/src/test/java/org/pragmatica/aether/e2e/ChaosE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/ClusterFormationE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/NodeFailureE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/RollingUpdateE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/SliceDeploymentE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherCluster.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherNodeContainer.javaexample-slice/README.mdexample-slice/pom.xmlexamples/order-demo/pom.xmlexamples/order-demo/run.shforge/pom.xmlinfra-services/artifact-repo/pom.xmlinfra-services/pom.xmlnode/pom.xmlnode/src/main/java/org/pragmatica/aether/api/ManagementServer.javanode/src/main/java/org/pragmatica/aether/endpoint/EndpointRegistry.javanode/src/main/java/org/pragmatica/aether/metrics/observability/AetherMetrics.javanode/src/main/java/org/pragmatica/aether/metrics/observability/ObservabilityRegistry.javanode/src/main/java/org/pragmatica/aether/update/CleanupPolicy.javanode/src/main/java/org/pragmatica/aether/update/HealthThresholds.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdate.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdateError.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdateManager.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdateState.javanode/src/main/java/org/pragmatica/aether/update/VersionRouting.javanode/src/test/java/org/pragmatica/aether/node/AetherNodeIT.javanode/src/test/java/org/pragmatica/aether/node/ClusterFailoverIT.javapom.xmlscript/aether-forge.shscript/aether-node.shscript/aether.shslice-annotations/pom.xmlslice-api/pom.xmlslice/pom.xmlslice/src/main/java/org/pragmatica/aether/artifact/ArtifactBase.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherKey.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherValue.java
🧰 Additional context used
📓 Path-based instructions (10)
**/*.{java,ts,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
Use
Promise<T>,Result<T>, orOption<T>for return types instead ofPromise<Result<T>>- failures flow through Promise directly
Files:
node/src/main/java/org/pragmatica/aether/update/RollingUpdateState.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/SliceDeploymentE2ETest.javanode/src/main/java/org/pragmatica/aether/metrics/observability/ObservabilityRegistry.javanode/src/main/java/org/pragmatica/aether/update/HealthThresholds.javanode/src/main/java/org/pragmatica/aether/update/CleanupPolicy.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherKey.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdateError.javacluster/src/test/java/org/pragmatica/cluster/consensus/rabia/infrastructure/TestCluster.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/ChaosE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/NodeFailureE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/ClusterFormationE2ETest.javanode/src/main/java/org/pragmatica/aether/update/VersionRouting.javanode/src/test/java/org/pragmatica/aether/node/AetherNodeIT.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherCluster.javacluster/src/main/java/org/pragmatica/cluster/node/rabia/CustomClasses.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdate.javanode/src/main/java/org/pragmatica/aether/endpoint/EndpointRegistry.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherNodeContainer.javacluster/src/test/java/org/pragmatica/cluster/consensus/rabia/MessageSemanticsIT.javaslice/src/main/java/org/pragmatica/aether/artifact/ArtifactBase.javacluster/src/main/java/org/pragmatica/cluster/node/rabia/RabiaNode.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/RollingUpdateE2ETest.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherValue.javacli/src/main/java/org/pragmatica/aether/cli/AetherCli.javacluster/src/test/java/org/pragmatica/node/RabiaNodeNettyIT.javanode/src/main/java/org/pragmatica/aether/metrics/observability/AetherMetrics.javanode/src/main/java/org/pragmatica/aether/api/ManagementServer.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdateManager.javanode/src/test/java/org/pragmatica/aether/node/ClusterFailoverIT.java
**/*.java
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.java: Parse, don't validate - construct valid objects only when validation succeeds usingResultwithVerifyfor parse operations
Never throw business exceptions - all failures flow throughResultorPromiseas typedCausesealed interfaces
Use factory naming conventionTypeName.typeName(...)with lowercase-first method names for creating instances
Use sealed interfaces for domain-specific error hierarchies extendingCause(e.g.,SliceError,RegistrationError,RepositoryError)
UsePromise.lift()andResult.lift()for exception-prone operations instead of try-catch blocks
Use records for data carriers and implementations throughout the codebase
Prefer method references over lambdas when the lambda only calls a single method (e.g.,.map(Artifact::asString)over.map(a -> a.asString()))
All domain objects must be immutable records; useList.of(),Map.of(),Set.of()for collections instead of mutable alternatives
Use exactly one design pattern per function: Leaf (single operation), Sequencer (linear chain), Fork-Join (parallel), Condition (branching), or Iteration (collection processing)
Use adapter leaves for all I/O operations (database, HTTP, file system) to ensure framework independence
Apply set timeouts as close to actual operations as possible; avoid timeouts at the end of Promise chains as they don't cancel operations
Use sealed interfaces for state machines and error hierarchies to provide exhaustive pattern matching in Java
Files:
node/src/main/java/org/pragmatica/aether/update/RollingUpdateState.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/SliceDeploymentE2ETest.javanode/src/main/java/org/pragmatica/aether/metrics/observability/ObservabilityRegistry.javanode/src/main/java/org/pragmatica/aether/update/HealthThresholds.javanode/src/main/java/org/pragmatica/aether/update/CleanupPolicy.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherKey.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdateError.javacluster/src/test/java/org/pragmatica/cluster/consensus/rabia/infrastructure/TestCluster.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/ChaosE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/NodeFailureE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/ClusterFormationE2ETest.javanode/src/main/java/org/pragmatica/aether/update/VersionRouting.javanode/src/test/java/org/pragmatica/aether/node/AetherNodeIT.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherCluster.javacluster/src/main/java/org/pragmatica/cluster/node/rabia/CustomClasses.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdate.javanode/src/main/java/org/pragmatica/aether/endpoint/EndpointRegistry.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherNodeContainer.javacluster/src/test/java/org/pragmatica/cluster/consensus/rabia/MessageSemanticsIT.javaslice/src/main/java/org/pragmatica/aether/artifact/ArtifactBase.javacluster/src/main/java/org/pragmatica/cluster/node/rabia/RabiaNode.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/RollingUpdateE2ETest.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherValue.javacli/src/main/java/org/pragmatica/aether/cli/AetherCli.javacluster/src/test/java/org/pragmatica/node/RabiaNodeNettyIT.javanode/src/main/java/org/pragmatica/aether/metrics/observability/AetherMetrics.javanode/src/main/java/org/pragmatica/aether/api/ManagementServer.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdateManager.javanode/src/test/java/org/pragmatica/aether/node/ClusterFailoverIT.java
**/{node,cluster,slice}/**/*.java
📄 CodeRabbit inference engine (CLAUDE.md)
All cluster state must flow through KV-Store; ValuePut/ValueRemove notifications drive state changes; use MessageRouter pattern for decoupled component communication
Files:
node/src/main/java/org/pragmatica/aether/update/RollingUpdateState.javanode/src/main/java/org/pragmatica/aether/metrics/observability/ObservabilityRegistry.javanode/src/main/java/org/pragmatica/aether/update/HealthThresholds.javanode/src/main/java/org/pragmatica/aether/update/CleanupPolicy.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherKey.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdateError.javacluster/src/test/java/org/pragmatica/cluster/consensus/rabia/infrastructure/TestCluster.javanode/src/main/java/org/pragmatica/aether/update/VersionRouting.javanode/src/test/java/org/pragmatica/aether/node/AetherNodeIT.javacluster/src/main/java/org/pragmatica/cluster/node/rabia/CustomClasses.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdate.javanode/src/main/java/org/pragmatica/aether/endpoint/EndpointRegistry.javacluster/src/test/java/org/pragmatica/cluster/consensus/rabia/MessageSemanticsIT.javaslice/src/main/java/org/pragmatica/aether/artifact/ArtifactBase.javacluster/src/main/java/org/pragmatica/cluster/node/rabia/RabiaNode.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherValue.javacluster/src/test/java/org/pragmatica/node/RabiaNodeNettyIT.javanode/src/main/java/org/pragmatica/aether/metrics/observability/AetherMetrics.javanode/src/main/java/org/pragmatica/aether/api/ManagementServer.javanode/src/main/java/org/pragmatica/aether/update/RollingUpdateManager.javanode/src/test/java/org/pragmatica/aether/node/ClusterFailoverIT.java
**/src/test/java/**/*.java
📄 CodeRabbit inference engine (CLAUDE.md)
**/src/test/java/**/*.java: Test classes should be package-private (no visibility modifier) with descriptive test method names using underscores:method_scenario_expectation()
For Promise success testing, use.await()to block, then test like Result with.onSuccess()and.onFailure()callbacks
For Result success testing, use.onSuccess()with lambda assertions; for failure testing, use.onSuccessRun(Assertions::fail)followed by failure assertions
For complex object construction in tests, useResult.all()for multiple component validation
Include roundtrip tests for all parseable types to ensure serialization/deserialization consistency
Files:
e2e-tests/src/test/java/org/pragmatica/aether/e2e/SliceDeploymentE2ETest.javacluster/src/test/java/org/pragmatica/cluster/consensus/rabia/infrastructure/TestCluster.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/ChaosE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/NodeFailureE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/ClusterFormationE2ETest.javanode/src/test/java/org/pragmatica/aether/node/AetherNodeIT.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherCluster.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherNodeContainer.javacluster/src/test/java/org/pragmatica/cluster/consensus/rabia/MessageSemanticsIT.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/RollingUpdateE2ETest.javacluster/src/test/java/org/pragmatica/node/RabiaNodeNettyIT.javanode/src/test/java/org/pragmatica/aether/node/ClusterFailoverIT.java
**/src/main/java/**/metrics/**/*.java
📄 CodeRabbit inference engine (CLAUDE.md)
Metrics collection uses MessageRouter without consensus I/O; all nodes receive cluster-wide metrics snapshot every 1 second with 2-hour sliding window for pattern detection
Files:
node/src/main/java/org/pragmatica/aether/metrics/observability/ObservabilityRegistry.javanode/src/main/java/org/pragmatica/aether/metrics/observability/AetherMetrics.java
**/src/main/java/**/kvstore/**/*.java
📄 CodeRabbit inference engine (CLAUDE.md)
For KV-Store keys, implement sealed interface
AetherKeywith static factory methods and parsing logic; use structured pattern matching for key validation
Files:
slice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherKey.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherValue.java
**/src/main/java/**/slice/**/*.java
📄 CodeRabbit inference engine (CLAUDE.md)
**/src/main/java/**/slice/**/*.java: SliceStore operations must include proper timeout configuration; apply timeout at the operation level, not at the chain end
Slice class loading must use hybrid ClassLoader model for isolation while sharing Pragmatica framework classes; implement via SliceClassLoader
Files:
slice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherKey.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherValue.java
**/src/main/java/**/cluster/**/*.java
📄 CodeRabbit inference engine (CLAUDE.md)
Use Rabia consensus protocol for cluster-wide state consistency with deterministic leader selection (first node in topology)
Files:
cluster/src/main/java/org/pragmatica/cluster/node/rabia/CustomClasses.javacluster/src/main/java/org/pragmatica/cluster/node/rabia/RabiaNode.java
**/src/main/java/**/cli/**/*.java
📄 CodeRabbit inference engine (CLAUDE.md)
CLI implementation (AetherCli) must support both REPL and batch modes for cluster management operations
Files:
cli/src/main/java/org/pragmatica/aether/cli/AetherCli.java
**/src/main/java/**/api/**/*.java
📄 CodeRabbit inference engine (CLAUDE.md)
ManagementServer must provide HTTP API for cluster management; use REST endpoints to expose cluster operations and state management
Files:
node/src/main/java/org/pragmatica/aether/api/ManagementServer.java
🧠 Learnings (14)
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Applies to **/src/main/java/**/forge/**/*.java : Aether Forge must provide standalone simulator with visual dashboard for load and chaos testing; implement via ForgeServer, ForgeCluster, and ForgeApiHandler
Applied to files:
forge/pom.xmlexamples/order-demo/run.shdocker/aether-forge/Dockerfilescript/aether-forge.shdocker/docker-compose.ymle2e-tests/src/test/java/org/pragmatica/aether/e2e/ChaosE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/ClusterFormationE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherCluster.java
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Applies to **/src/main/java/**/slice/**/*.java : Slice class loading must use hybrid ClassLoader model for isolation while sharing Pragmatica framework classes; implement via SliceClassLoader
Applied to files:
example-slice/README.mddocs/guide/migration-guide.mde2e-tests/src/test/java/org/pragmatica/aether/e2e/SliceDeploymentE2ETest.javaslice/pom.xmlslice-annotations/pom.xmlexample-slice/pom.xmldocs/guide/getting-started.mdslice-api/pom.xml
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Applies to **/src/main/java/**/deployment/node/**/*.java : NodeDeploymentManager must watch KV-Store for slice state changes and coordinate with SliceStore to perform lifecycle operations on local node
Applied to files:
e2e-tests/src/test/java/org/pragmatica/aether/e2e/SliceDeploymentE2ETest.javadocs/architecture-overview.mdnode/src/test/java/org/pragmatica/aether/node/ClusterFailoverIT.java
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Applies to **/src/main/java/**/deployment/cluster/**/*.java : ClusterDeploymentManager must watch KV-Store for slice state changes, write allocation decisions directly to slice-node-keys with LOAD state, and handle reconciliation on topology changes
Applied to files:
e2e-tests/src/test/java/org/pragmatica/aether/e2e/SliceDeploymentE2ETest.javadocs/architecture-overview.md
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Applies to **/src/main/java/**/cli/**/*.java : CLI implementation (AetherCli) must support both REPL and batch modes for cluster management operations
Applied to files:
script/aether.shcli/pom.xmle2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherCluster.javacli/src/main/java/org/pragmatica/aether/cli/AetherCli.java
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Applies to **/src/main/java/**/kvstore/**/*.java : For KV-Store keys, implement sealed interface `AetherKey` with static factory methods and parsing logic; use structured pattern matching for key validation
Applied to files:
slice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherKey.javanode/src/test/java/org/pragmatica/aether/node/AetherNodeIT.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherValue.javanode/src/test/java/org/pragmatica/aether/node/ClusterFailoverIT.java
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Applies to **/src/main/java/**/blueprint/**/*.java : Blueprint DSL parser must support JSON format for slice artifact specification with instance counts; store in KV-Store under blueprint/{artifact} key
Applied to files:
slice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherKey.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherValue.java
📚 Learning: 2025-12-28T23:49:16.532Z
Learnt from: siy
Repo: siy/aether PR: 19
File: node/src/main/java/org/pragmatica/aether/node/AetherNode.java:343-355
Timestamp: 2025-12-28T23:49:16.532Z
Learning: In AetherNode.java, the compositeRepository method intentionally uses only the first repository (not multi-repository fallback like SliceStoreImpl) because BlueprintService parses text blueprints where fallback to another repository wouldn't help (same artifact would have the same result), unlike SliceStoreImpl which loads JARs where trying multiple sources makes sense. This simplification is documented in the Javadoc and will be extended when there's a real use case.
Applied to files:
slice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherKey.javaslice/src/main/java/org/pragmatica/aether/slice/kvstore/AetherValue.javanode/src/main/java/org/pragmatica/aether/api/ManagementServer.java
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Applies to **/*.java : Use sealed interfaces for domain-specific error hierarchies extending `Cause` (e.g., `SliceError`, `RegistrationError`, `RepositoryError`)
Applied to files:
node/src/main/java/org/pragmatica/aether/update/RollingUpdateError.java
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Applies to **/src/main/java/**/cluster/**/*.java : Use Rabia consensus protocol for cluster-wide state consistency with deterministic leader selection (first node in topology)
Applied to files:
cluster/src/test/java/org/pragmatica/cluster/consensus/rabia/infrastructure/TestCluster.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/ChaosE2ETest.javae2e-tests/src/test/java/org/pragmatica/aether/e2e/ClusterFormationE2ETest.javacluster/src/main/java/org/pragmatica/cluster/node/rabia/CustomClasses.javacluster/src/test/java/org/pragmatica/cluster/consensus/rabia/MessageSemanticsIT.javacluster/src/main/java/org/pragmatica/cluster/node/rabia/RabiaNode.javacluster/src/test/java/org/pragmatica/node/RabiaNodeNettyIT.java
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Applies to **/{node,cluster,slice}/**/*.java : All cluster state must flow through KV-Store; ValuePut/ValueRemove notifications drive state changes; use MessageRouter pattern for decoupled component communication
Applied to files:
cluster/src/test/java/org/pragmatica/cluster/consensus/rabia/infrastructure/TestCluster.javacluster/src/main/java/org/pragmatica/cluster/node/rabia/RabiaNode.java
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Applies to **/src/main/java/**/metrics/**/*.java : Metrics collection uses MessageRouter without consensus I/O; all nodes receive cluster-wide metrics snapshot every 1 second with 2-hour sliding window for pattern detection
Applied to files:
docs/architecture-overview.mdcluster/src/main/java/org/pragmatica/cluster/node/rabia/RabiaNode.javanode/src/main/java/org/pragmatica/aether/metrics/observability/AetherMetrics.java
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Implement four-layer autonomy architecture where Layer 1 (DecisionTreeController) is mandatory and all other layers (SLM, LLM, User) are optional enhancements with graceful degradation
Applied to files:
docs/architecture-overview.md
📚 Learning: 2026-01-01T08:49:19.264Z
Learnt from: CR
Repo: siy/aether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-01T08:49:19.264Z
Learning: Applies to **/src/main/java/**/api/**/*.java : ManagementServer must provide HTTP API for cluster management; use REST endpoints to expose cluster operations and state management
Applied to files:
node/src/main/java/org/pragmatica/aether/api/ManagementServer.java
🧬 Code graph analysis (6)
e2e-tests/src/test/java/org/pragmatica/aether/e2e/SliceDeploymentE2ETest.java (1)
e2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherCluster.java (1)
AetherCluster(39-288)
e2e-tests/src/test/java/org/pragmatica/aether/e2e/ChaosE2ETest.java (1)
e2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherCluster.java (1)
AetherCluster(39-288)
e2e-tests/src/test/java/org/pragmatica/aether/e2e/NodeFailureE2ETest.java (1)
e2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherCluster.java (1)
AetherCluster(39-288)
node/src/test/java/org/pragmatica/aether/node/AetherNodeIT.java (3)
cluster/src/test/java/org/pragmatica/cluster/consensus/rabia/MessageSemanticsIT.java (1)
Disabled(28-265)cluster/src/test/java/org/pragmatica/node/RabiaNodeNettyIT.java (1)
Disabled(38-191)node/src/test/java/org/pragmatica/aether/node/ClusterFailoverIT.java (1)
Disabled(44-530)
e2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherCluster.java (1)
e2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherNodeContainer.java (1)
AetherNodeContainer(26-247)
node/src/test/java/org/pragmatica/aether/node/ClusterFailoverIT.java (1)
node/src/test/java/org/pragmatica/aether/node/AetherNodeIT.java (1)
Disabled(38-291)
🪛 actionlint (1.7.9)
.github/workflows/ci.yml
125-125: shellcheck reported issue in this script: SC2086:info:1:86: Double quote to prevent globbing and word splitting
(shellcheck)
🪛 markdownlint-cli2 (0.18.1)
docs/architecture-overview.md
219-219: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
310-310: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
| HEALTHCHECK --interval=10s --timeout=5s --start-period=60s --retries=3 \ | ||
| CMD wget --no-verbose --tries=1 --spider http://localhost:${FORGE_PORT}/api/metrics || exit 1 |
There was a problem hiding this comment.
Verify wget availability in Alpine or install it explicitly.
Alpine Linux's busybox wget may not support all flags used here (e.g., --spider, --tries). Consider either installing wget explicitly via RUN apk add --no-cache wget before the health check, or switching to curl (also requires installation) or a simpler approach using nc or sh -c.
🔎 Proposed fix: Install wget or use alternative
Option 1: Install wget explicitly
+# Install wget for health checks
+RUN apk add --no-cache wget
+
WORKDIR /appOption 2: Use curl instead
+# Install curl for health checks
+RUN apk add --no-cache curl
+
WORKDIR /appThen update the health check:
-HEALTHCHECK --interval=10s --timeout=5s --start-period=60s --retries=3 \
- CMD wget --no-verbose --tries=1 --spider http://localhost:${FORGE_PORT}/api/metrics || exit 1
+HEALTHCHECK --interval=10s --timeout=5s --start-period=60s --retries=3 \
+ CMD curl -f http://localhost:${FORGE_PORT}/api/metrics || exit 1Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In docker/aether-forge/Dockerfile around lines 34-35 the HEALTHCHECK uses wget
flags that may not be supported by Alpine's busybox wget; install a full wget or
replace the command with a compatible tool. Either add a RUN apk add --no-cache
wget earlier in the Dockerfile so the healthcheck uses GNU wget that supports
--spider and --tries, or change the HEALTHCHECK to use curl (and add RUN apk add
--no-cache curl) or a POSIX-safe shell probe (e.g., sh -c with nc or simple HTTP
GET) ensuring the chosen tool is installed before the HEALTHCHECK line.
| ``` | ||
| PENDING → DEPLOYING → DEPLOYED → ROUTING → VALIDATING → COMPLETING → COMPLETED | ||
| ↓ ↓ | ||
| ROLLING_BACK ROLLED_BACK | ||
| ↓ | ||
| FAILED | ||
| ``` |
There was a problem hiding this comment.
Add language identifier to fenced code block.
The state machine diagram is in a fenced code block without a language identifier. Add text or mermaid (if converting to a proper diagram) to resolve the markdown linting warning.
🔎 Proposed fix
**State Machine**:
-```
+```text
PENDING → DEPLOYING → DEPLOYED → ROUTING → VALIDATING → COMPLETING → COMPLETED
↓ ↓
ROLLING_BACK ROLLED_BACK
↓
FAILED</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
219-219: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In docs/architecture-overview.md around lines 219 to 225, the fenced code block
containing the state machine diagram lacks a language identifier; change the
opening fence from ``` to ```text (or ```mermaid if you want to convert it to a
Mermaid flowchart) so the markdown linter recognizes the block, and keep the
existing diagram content unchanged.
| ``` | ||
| version-routing/{group-id}:{artifact-id} → { | ||
| "oldVersion": "1.0.0", | ||
| "newVersion": "2.0.0", | ||
| "newWeight": 1, | ||
| "oldWeight": 3, | ||
| "updatedAt": 1234567890 | ||
| } | ||
|
|
||
| rolling-update/{update-id} → { | ||
| "updateId": "abc123", | ||
| "artifactBase": "org.example:order-processor", | ||
| "oldVersion": "1.0.0", | ||
| "newVersion": "2.0.0", | ||
| "state": "ROUTING", | ||
| "newWeight": 1, | ||
| "oldWeight": 3, | ||
| "newInstances": 3, | ||
| "maxErrorRate": 0.01, | ||
| "maxLatencyMs": 500, | ||
| "requireManualApproval": false, | ||
| "cleanupPolicy": "GRACE_PERIOD", | ||
| "createdAt": 1234567890, | ||
| "updatedAt": 1234567890 | ||
| } | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Add language identifier to fenced code block.
The rolling update schema examples are in fenced code blocks without language identifiers. Add json to resolve the markdown linting warning and enable proper syntax highlighting.
🔎 Proposed fix
### Rolling Update Schema
-```
+```json
version-routing/{group-id}:{artifact-id} → {
"oldVersion": "1.0.0",📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| version-routing/{group-id}:{artifact-id} → { | |
| "oldVersion": "1.0.0", | |
| "newVersion": "2.0.0", | |
| "newWeight": 1, | |
| "oldWeight": 3, | |
| "updatedAt": 1234567890 | |
| } | |
| rolling-update/{update-id} → { | |
| "updateId": "abc123", | |
| "artifactBase": "org.example:order-processor", | |
| "oldVersion": "1.0.0", | |
| "newVersion": "2.0.0", | |
| "state": "ROUTING", | |
| "newWeight": 1, | |
| "oldWeight": 3, | |
| "newInstances": 3, | |
| "maxErrorRate": 0.01, | |
| "maxLatencyMs": 500, | |
| "requireManualApproval": false, | |
| "cleanupPolicy": "GRACE_PERIOD", | |
| "createdAt": 1234567890, | |
| "updatedAt": 1234567890 | |
| } | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
310-310: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In docs/architecture-overview.md around lines 310 to 336 the fenced code blocks
showing the version-routing and rolling-update JSON examples lack a language
identifier; update both opening fences to use ```json so the blocks become
fenced as JSON (i.e., replace ``` with ```json for each example) to satisfy the
markdown linter and enable JSON syntax highlighting.
| aether update list | ||
|
|
||
| # Adjust traffic routing (ratio new:old) | ||
| aether update routing <updateId> -r <ratio> |
There was a problem hiding this comment.
Document the -r flag for the routing command.
The routing command uses -r <ratio> but this flag is not documented in the options section (lines 222-227). Consider adding a brief note explaining that -r accepts ratio format like "1:3" or "3:1".
🤖 Prompt for AI Agents
In docs/guide/cli-reference.md around line 236, the CLI example uses the
undocumented -r flag for routing; update the options section (around lines
222-227) to document -r by adding a brief note that -r accepts a ratio string
(examples: "1:3" or "3:1") and explain that it specifies the relative routing
weight between targets, including valid formats and a short example of usage.
| public String deploy(String artifact, int instances) { | ||
| var body = "{\"artifact\":\"" + artifact + "\",\"instances\":" + instances + "}"; | ||
| return post("/deploy", body); | ||
| } | ||
|
|
||
| /** | ||
| * Scales a deployed slice. | ||
| * | ||
| * @param artifact artifact coordinates | ||
| * @param instances target instance count | ||
| * @return scale response JSON | ||
| */ | ||
| public String scale(String artifact, int instances) { | ||
| var body = "{\"artifact\":\"" + artifact + "\",\"instances\":" + instances + "}"; | ||
| return post("/scale", body); | ||
| } | ||
|
|
||
| /** | ||
| * Undeploys a slice from the cluster. | ||
| * | ||
| * @param artifact artifact coordinates | ||
| * @return undeploy response JSON | ||
| */ | ||
| public String undeploy(String artifact) { | ||
| var body = "{\"artifact\":\"" + artifact + "\"}"; | ||
| return post("/undeploy", body); | ||
| } |
There was a problem hiding this comment.
Manual JSON construction is vulnerable to injection and malformation.
All deployment methods construct JSON via string concatenation without escaping special characters. If artifact contains quotes, backslashes, or control characters, the resulting JSON will be malformed or could enable injection attacks.
Example: deploy("test:\"hack\":1.0", 1) produces invalid JSON: {"artifact":"test:"hack":1.0","instances":1}
🔎 Recommended fix: Use a JSON library or escape inputs
Solution 1 (preferred): Use a JSON library like Jackson or Gson:
private String toDeployJson(String artifact, int instances) {
return new JSONObject()
.put("artifact", artifact)
.put("instances", instances)
.toString();
}
public String deploy(String artifact, int instances) {
return post("/deploy", toDeployJson(artifact, instances));
}Solution 2 (minimal): Escape strings manually:
private static String escapeJson(String value) {
return value.replace("\\", "\\\\")
.replace("\"", "\\\"")
.replace("\n", "\\n")
.replace("\r", "\\r")
.replace("\t", "\\t");
}
public String deploy(String artifact, int instances) {
var body = "{\"artifact\":\"" + escapeJson(artifact) + "\",\"instances\":" + instances + "}";
return post("/deploy", body);
}🤖 Prompt for AI Agents
e2e-tests/src/test/java/org/pragmatica/aether/e2e/containers/AetherNodeContainer.java
lines 179-205: the deploy/scale/undeploy methods build JSON by string
concatenation which breaks on quotes/backslashes and can allow injection;
replace manual concatenation with a proper JSON builder (preferred: use
Jackson/Gson/JSONObject to build a Map/object and serialize to a string) or at
minimum extract an escapeJson helper and apply it to artifact before embedding;
refactor to a private helper (e.g., toDeployJson/toUndeployJson) used by
deploy/scale/undeploy so all requests produce well-formed, escaped JSON.
| @Test | ||
| void minorityPartition_quorumLost_thenRecovered() { | ||
| // Kill majority (3 of 5) | ||
| cluster.killNode("node-1"); | ||
| cluster.killNode("node-2"); | ||
| cluster.killNode("node-3"); | ||
|
|
||
| assertThat(cluster.runningNodeCount()).isEqualTo(2); | ||
|
|
||
| // Remaining nodes should report degraded/unhealthy | ||
| var health = cluster.anyNode().getHealth(); | ||
| // May contain error or degraded status | ||
|
|
||
| // Restore one node to regain quorum (3 of 5) | ||
| cluster.restartNode("node-1"); | ||
| cluster.awaitQuorum(); | ||
|
|
||
| // Cluster should be healthy again | ||
| var restoredHealth = cluster.anyNode().getHealth(); | ||
| assertThat(restoredHealth).doesNotContain("\"error\""); | ||
| } |
There was a problem hiding this comment.
Unused variable health on line 152.
The variable is assigned but never used for assertions. Either add an assertion or remove the variable.
🔎 Suggested fix
assertThat(cluster.runningNodeCount()).isEqualTo(2);
- // Remaining nodes should report degraded/unhealthy
- var health = cluster.anyNode().getHealth();
- // May contain error or degraded status
+ // Remaining nodes should report degraded/unhealthy (quorum lost)
+ // Note: Not asserting specific health status as behavior may vary🤖 Prompt for AI Agents
In e2e-tests/src/test/java/org/pragmatica/aether/e2e/NodeFailureE2ETest.java
around lines 142 to 162, the local variable `health` (line 152) is assigned but
never used; either remove the assignment or add an assertion against it. Fix by
replacing the unused assignment with a meaningful assertion that validates the
pre-recovery degraded state (e.g., assert that `health` contains a
degraded/unhealthy indicator or contains "\"error\""), or simply remove the `var
health = ...` line if you don’t need to check the intermediate state.
| private String get(String path) { | ||
| return cluster.anyNode().getHealth().replace("/health", path); | ||
| } |
There was a problem hiding this comment.
Fix the get() helper implementation.
The get() method incorrectly attempts string replacement on the health JSON response. This should construct a proper HTTP GET request to the specified path.
🔎 Proposed fix
Based on the AetherNodeContainer API pattern, the implementation should likely be:
private String get(String path) {
- return cluster.anyNode().getHealth().replace("/health", path);
+ // Needs actual HTTP client implementation similar to getHealth()
+ // For now, this explains why the test is @Disabled
+ throw new UnsupportedOperationException("HTTP GET not yet implemented");
}Or if AetherNodeContainer provides a generic request method, use that instead.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| private String get(String path) { | |
| return cluster.anyNode().getHealth().replace("/health", path); | |
| } | |
| private String get(String path) { | |
| // Needs actual HTTP client implementation similar to getHealth() | |
| // For now, this explains why the test is @Disabled | |
| throw new UnsupportedOperationException("HTTP GET not yet implemented"); | |
| } |
🤖 Prompt for AI Agents
In e2e-tests/src/test/java/org/pragmatica/aether/e2e/RollingUpdateE2ETest.java
around lines 256-258, the get(String path) helper wrongly does string
replacement on the health JSON result; replace it with a real HTTP GET using the
AetherNodeContainer API (call the node's GET/request method with the provided
path on cluster.anyNode(), e.g. cluster.anyNode().get(path) or
cluster.anyNode().request("GET", path) depending on available methods) and
return the response body; ensure you do not attempt to manipulate the health
JSON string and handle or propagate any IO/checked exceptions consistently with
surrounding tests.
| void scaleSlice_adjustsInstanceCount() { | ||
| // Deploy with 1 instance | ||
| cluster.anyNode().deploy(TEST_ARTIFACT, 1); | ||
| await().atMost(DEPLOY_TIMEOUT) | ||
| .until(() -> sliceIsActive(TEST_ARTIFACT)); | ||
|
|
||
| // Scale to 3 instances | ||
| var scaleResponse = cluster.anyNode().scale(TEST_ARTIFACT, 3); | ||
| assertThat(scaleResponse).doesNotContain("\"error\""); | ||
|
|
||
| // Wait for scale operation to complete | ||
| await().atMost(DEPLOY_TIMEOUT) | ||
| .pollInterval(Duration.ofSeconds(2)) | ||
| .until(() -> { | ||
| var slices = cluster.anyNode().getSlices(); | ||
| // Check for 3 instances (implementation-specific) | ||
| return slices.contains(TEST_ARTIFACT); | ||
| }); | ||
| } |
There was a problem hiding this comment.
Strengthen the scale verification assertion.
The scale test deploys with 1 instance, scales to 3, but only verifies that the artifact name is still present in the response. It doesn't actually confirm that the instance count changed to 3. This makes the test less effective at catching scaling bugs.
Consider verifying the actual instance count in the response, or checking that instances are distributed across multiple nodes. For example, you could parse the JSON response to extract the instance count or query individual nodes to verify the deployment distribution.
🤖 Prompt for AI Agents
In e2e-tests/src/test/java/org/pragmatica/aether/e2e/SliceDeploymentE2ETest.java
around lines 79 to 97, the test scales the slice but only asserts the artifact
name is present; update the verification to assert the actual instance count
equals 3 by either parsing the scaleResponse JSON for the instance count field
(and asserting it equals 3) or by querying cluster.anyNode().getSlices() (or
each node) to compute total instances for TEST_ARTIFACT and assert that total ==
3 inside the await condition; keep the existing await/pollInterval but replace
the boolean check with a precise count check and fail the test if the count does
not reach 3 within DEPLOY_TIMEOUT.
| private final MultiThreadIoEventLoopGroup workerGroup; | ||
| private final AlertManager alertManager; | ||
| private final DashboardMetricsPublisher metricsPublisher; | ||
| private final ObservabilityRegistry observability; |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, find and examine ManagementServer.java
git ls-files | grep -i managementserver
# Search for RequestMetricsCapture usage
rg -i 'requestmetricscapture' --type java
# Check for request metrics collection patterns
rg -n 'Timer\.|Counter\.|metrics.*request|request.*metrics' node/src/main/java/org/pragmatica/aether/api/ --type java
# Check HttpRequestHandler for metrics integration
fd 'HttpRequestHandler' --type fRepository: siy/aether
Length of output: 120
🏁 Script executed:
# Read the ManagementServer.java file to examine observability usage
wc -l node/src/main/java/org/pragmatica/aether/api/ManagementServer.java
# Get the content with line numbers
cat -n node/src/main/java/org/pragmatica/aether/api/ManagementServer.java
# Search for RequestMetricsCapture or similar patterns
rg -i 'requestmetricscapture' --type java -A 10 -B 5
# Search more broadly for metrics capture in the entire project
rg 'MetricsCapture|RequestMetrics' --type java
# Check if there's an HttpRequestHandler file
fd 'HttpRequestHandler' --extension javaRepository: siy/aether
Length of output: 45332
🏁 Script executed:
# Search more broadly for RequestMetricsCapture and metrics capture patterns
rg -i 'requestmetricscapture|metricscapture' --type java
# Search for Timer and Counter usage in HTTP handlers
rg '(Timer|Counter|Gauge)\.' --type java -A 3 | head -50
# Check if observability is used elsewhere for request metrics
rg 'observability\.' node/src/main/java/org/pragmatica/aether/api/ --type java -A 2
# Look for metrics capture in similar handler or middleware patterns
rg 'channelRead|handleGet|handlePost' --type java -B 2 -A 10 | grep -i 'metric\|timer\|observe'
# Search for any mention of "request metrics" in comments or code
rg -i 'request.*metric|metric.*request' --type javaRepository: siy/aether
Length of output: 7023
🏁 Script executed:
# Examine AetherMetrics to understand the httpRequest metrics interface
fd 'AetherMetrics' --type f
# Read the AetherMetrics file
cat -n node/src/main/java/org/pragmatica/aether/metrics/observability/AetherMetrics.java
# Search for usages of httpRequest metric
rg 'httpRequest' --type java -B 3 -A 3
# Check if PromiseMetrics is being used anywhere
rg 'PromiseMetrics' --type java -B 2 -A 2Repository: siy/aether
Length of output: 19947
🏁 Script executed:
# Check if AetherMetrics is created from observability anywhere in ManagementServer
rg 'AetherMetrics' node/src/main/java/org/pragmatica/aether/api/ --type java
# Check if observability.combined or observability.timer is used anywhere
rg 'observability\.(combined|timer|counter)' --type java
# Verify what methods are available on ObservabilityRegistry
fd 'ObservabilityRegistry' --type f
cat -n node/src/main/java/org/pragmatica/aether/metrics/observability/ObservabilityRegistry.java | head -80Repository: siy/aether
Length of output: 3079
🏁 Script executed:
# Final verification: confirm no AetherMetrics usage in ManagementServer
rg 'AetherMetrics' node/src/main/java/org/pragmatica/aether/api/ManagementServer.java
# Check if httpRequest metrics are captured anywhere in the codebase
rg 'httpRequest\(' --type java | grep -v 'interface\|PromiseMetrics'Repository: siy/aether
Length of output: 36
Integrate HTTP request metrics collection into HttpRequestHandler.
The ObservabilityRegistry is initialized and wired to HttpRequestHandler, but is only used for the Prometheus scrape endpoint. HTTP request-level metrics (timing, status codes, endpoint paths) are not being captured, despite AetherMetrics providing httpRequest(method, path) and httpRequestCounter(method, path, status) methods designed for this purpose. Create an AetherMetrics instance from observability and record metrics for each request in channelRead0() using the appropriate lifecycle methods.
🤖 Prompt for AI Agents
In node/src/main/java/org/pragmatica/aether/api/ManagementServer.java around
line 89, the ObservabilityRegistry field is present but HTTP request-level
metrics are not recorded; create an AetherMetrics instance from the
observability registry (e.g., observability.metrics().aetherMetrics()) and
integrate it into HttpRequestHandler.channelRead0(): when a request arrives call
httpRequest(method, path) to obtain a timing/context object, start timing before
processing, stop/observe timing after generating the response, and call
httpRequestCounter(method, path, status) with the final response status; ensure
the timing/stop is executed in a finally block to handle exceptions and that the
metrics instance is injected into the handler (constructor or field) where the
Prometheus scrape use remains unchanged.
| public static HealthThresholds withErrorRate(double maxErrorRate) { | ||
| return new HealthThresholds(maxErrorRate, DEFAULT.maxLatencyMs, false); | ||
| } | ||
|
|
||
| /** | ||
| * Creates thresholds with default values and custom latency. | ||
| */ | ||
| public static HealthThresholds withLatency(long maxLatencyMs) { | ||
| return new HealthThresholds(DEFAULT.maxErrorRate, maxLatencyMs, false); | ||
| } |
There was a problem hiding this comment.
Convenience methods bypass validation.
withErrorRate() and withLatency() call the record constructor directly, bypassing the validation in healthThresholds(). Invalid values (e.g., negative error rate) could be created.
🔎 Proposed fix to use validated factory
public static HealthThresholds withErrorRate(double maxErrorRate) {
- return new HealthThresholds(maxErrorRate, DEFAULT.maxLatencyMs, false);
+ return healthThresholds(maxErrorRate, DEFAULT.maxLatencyMs, false);
}
public static HealthThresholds withLatency(long maxLatencyMs) {
- return new HealthThresholds(DEFAULT.maxErrorRate, maxLatencyMs, false);
+ return healthThresholds(DEFAULT.maxErrorRate, maxLatencyMs, false);
}Note: If you adopt Result for healthThresholds(), these methods would need to return Result<HealthThresholds> as well, or you could use .orElseThrow() since they only vary one parameter from known-good defaults.
Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In node/src/main/java/org/pragmatica/aether/update/HealthThresholds.java around
lines 53-62, the convenience methods withErrorRate(...) and withLatency(...)
currently call the record constructor directly and bypass validation; change
them to call the validated factory healthThresholds(maxErrorRate, maxLatencyMs)
with the appropriate default for the other parameter and handle the validation
Result by returning the contained HealthThresholds or throwing an
IllegalArgumentException (or a descriptive runtime exception) if validation
fails so the methods keep their HealthThresholds return type but cannot produce
invalid instances.
1 participant
Summary
Changes
Added
docker/aether-node/,docker/aether-forge/,docker-compose.yml)AetherNodeContainer,AetherCluster, cluster formation testsRollingUpdate,VersionRouting,RollingUpdateState)RollingUpdateManagerwith API endpoints and CLI commandsArtifactBasefor version-agnostic artifact identificationRequestMetricsCapture/metrics/dashboardFixed
Changed
Summary by CodeRabbit
New Features
Tests
CI/CD
✏️ Tip: You can customize this high-level summary in your review settings.