document expressions

Author: andrewazores

schema/openapi.yaml

@@ -1533,6 +1533,10 @@ paths:
         - Auth
   /api/v4/matchExpressions:
     get:
+      description: |
+        Retrieve a list of all currently defined Match Expressions. These objects cannot be created
+        independently in the current API definition, so each of these expressions will be associated with
+        an Automated Rule or Stored Credential.
       responses:
         "200":
           content:
@@ -1549,9 +1553,15 @@ paths:
           description: Not Allowed
       security:
         - SecurityScheme: []
+      summary: Retrieve a list of all currently defined Match Expressions
       tags:
         - Match Expressions
     post:
+      description: |
+        Given a list of Target IDs, retrieve each Target instance from the database, then return the list
+        filtered by the Targets which satisfy the Match Expression. If a given ID does not exist in the
+        database then the whole request will fail. The expression must evaluate to a boolean value for each
+        target. The match expression will not be stored.
       requestBody:
         content:
           application/json:
@@ -1570,6 +1580,7 @@ paths:
           description: Not Allowed
       security:
         - SecurityScheme: []
+      summary: Test a MatchExpression against a list of Targets
       tags:
         - Match Expressions
   /api/v4/matchExpressions/{id}:
@@ -1594,6 +1605,7 @@ paths:
           description: Not Allowed
       security:
         - SecurityScheme: []
+      summary: Retrieve a single Match Expression
       tags:
         - Match Expressions
   /api/v4/probes:

src/main/java/io/cryostat/expressions/MatchExpression.java

@@ -45,6 +45,14 @@
 import org.jboss.logging.Logger;
 import org.projectnessie.cel.tools.ScriptException;
 
+/**
+ * Match Expressions contain small snippets of Common Expression Language and are used to evaluate
+ * other resources' applicability to {@link io.cryostat.target.Target}s. {@link
+ * io.cryostat.rules.Rule}s and {@link io.cryostat.credentials.Credential}s use Match Expressions to
+ * determine the set of Targets they should apply to. When evaluating a Match Expression, Cryostat
+ * passes a slightly slimmed down and read-only representation of the Target instance into the
+ * expression context so that the expression can make assertions about the Target's properties.
+ */
 @Entity
 @EntityListeners(MatchExpression.Listener.class)
 public class MatchExpression extends PanacheEntity {

src/main/java/io/cryostat/expressions/MatchExpressionEvaluator.java

@@ -233,7 +233,7 @@ public static class MatchExpressionApplies extends Event {
     public static class ScriptCreation extends Event {}
 
     /**
-     * Restricted view of a {@link io.cryostat.targets.Target} with only particular
+     * Restricted read-only view of a {@link io.cryostat.targets.Target} with only particular
      * expression-relevant fields exposed, connection URI exposed as a String, etc.
      */
     private static record SimplifiedTarget(

src/main/java/io/cryostat/expressions/MatchExpressions.java

@@ -30,6 +30,7 @@
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.POST;
 import jakarta.ws.rs.Path;
+import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.jboss.logging.Logger;
 import org.jboss.resteasy.reactive.RestPath;
 import org.projectnessie.cel.tools.ScriptException;
@@ -43,6 +44,15 @@ public class MatchExpressions {
     @POST
     @RolesAllowed("read")
     @Blocking
+    @Operation(
+            summary = "Test a MatchExpression against a list of Targets",
+            description =
+                    """
+                    Given a list of Target IDs, retrieve each Target instance from the database, then return the list
+                    filtered by the Targets which satisfy the Match Expression. If a given ID does not exist in the
+                    database then the whole request will fail. The expression must evaluate to a boolean value for each
+                    target. The match expression will not be stored.
+                    """)
     public MatchedExpression test(RequestData requestData) throws ScriptException {
         var targets = new HashSet<Target>();
         if (requestData.targetIds == null) {
@@ -56,11 +66,20 @@ public MatchedExpression test(RequestData requestData) throws ScriptException {
     @GET
     @RolesAllowed("read")
     @Blocking
+    @Operation(
+            summary = "Retrieve a list of all currently defined Match Expressions",
+            description =
+                    """
+                    Retrieve a list of all currently defined Match Expressions. These objects cannot be created
+                    independently in the current API definition, so each of these expressions will be associated with
+                    an Automated Rule or Stored Credential.
+                    """)
     public Multi<Map<String, Object>> list() {
         List<MatchExpression> exprs = MatchExpression.listAll();
         // FIXME hack so that this endpoint renders the response as the entity object with id and
         // script fields, rather than allowing Jackson serialization to handle it normally where it
-        // will be encoded as only the script as a raw string
+        // will be encoded as only the script as a raw string. This should be done using a JsonView
+        // or similar technique instead
         return Multi.createFrom()
                 .items(exprs.stream().map(expr -> Map.of("id", expr.id, "script", expr.script)));
     }
@@ -69,6 +88,7 @@ public Multi<Map<String, Object>> list() {
     @Path("/{id}")
     @RolesAllowed("read")
     @Blocking
+    @Operation(summary = "Retrieve a single Match Expression")
     public MatchedExpression get(@RestPath long id) throws ScriptException {
         return targetMatcher.match(MatchExpression.find("id", id).singleResult());
     }