Expose REST API endpoint to list workflow run events

Signed-off-by: nscuro <nscuro@protonmail.com>

Author: nscuro

api/src/main/openapi/components/schemas/list-workflow-run-events-response-item.yaml

@@ -0,0 +1,25 @@
+# This file is part of Dependency-Track.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) OWASP Foundation. All Rights Reserved.
+type: object
+properties:
+  sequence_number:
+    type: integer
+  event:
+    type: object
+    additionalProperties: true
+required:
+- sequence_number

api/src/main/openapi/components/schemas/list-workflow-run-events-response.yaml

@@ -0,0 +1,27 @@
+# This file is part of Dependency-Track.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) OWASP Foundation. All Rights Reserved.
+type: object
+allOf:
+  - $ref: "./paginated-response.yaml"
+properties:
+  events:
+    type: array
+    items:
+      $ref: "./list-workflow-run-events-response-item.yaml"
+required:
+- _pagination
+- events

api/src/main/openapi/openapi.yaml

@@ -158,6 +158,8 @@ paths:
     $ref: "./paths/workflow-instances__id_.yaml"
   /workflow-runs:
     $ref: "./paths/workflow-runs.yaml"
+  /workflow-runs/{id}/events:
+    $ref: "./paths/workflow-runs__id__events.yaml"
 
 components:
   securitySchemes:

api/src/main/openapi/paths/workflow-runs__id__events.yaml

@@ -0,0 +1,62 @@
+# This file is part of Dependency-Track.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) OWASP Foundation. All Rights Reserved.
+get:
+  operationId: listWorkflowRunEvents
+  summary: List all events of a workflow run
+  description: |-
+    Returns a paginated list of workflow run events, sorted by sequence number.
+    
+    **Note:** This is an internal API endpoint and may change without notice.
+    
+    Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission.
+  tags:
+  - Workflows
+  parameters:
+  - name: id
+    description: ID of the workflow run
+    in: path
+    schema:
+      type: string
+      format: uuid
+    required: true
+  - name: from_sequence_number
+    description: |-
+      Sequence number of the last seen event.
+      May be used to continuously poll for new events.
+      Can not be used together with `page_token`.
+    in: query
+    schema:
+      type: integer
+      minimum:
+  - $ref: "../components/parameters/pagination-limit.yaml"
+  - $ref: "../components/parameters/page-token.yaml"
+  - $ref: "../components/parameters/sort-direction.yaml"
+  responses:
+    "200":
+      description: Paginated list of workflow run events
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/list-workflow-run-events-response.yaml"
+    "400":
+      $ref: "../components/responses/invalid-request-error.yaml"
+    "401":
+      $ref: "../components/responses/generic-unauthorized-error.yaml"
+    "403":
+      $ref: "../components/responses/generic-forbidden-error.yaml"
+    default:
+      $ref: "../components/responses/generic-error.yaml"

apiserver/src/main/java/org/dependencytrack/resources/v2/ResourceConfig.java

@@ -25,11 +25,14 @@
 import alpine.server.filters.HeaderFilter;
 import alpine.server.filters.RequestIdFilter;
 import alpine.server.filters.RequestMdcEnrichmentFilter;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.ws.rs.ext.ContextResolver;
 import org.dependencytrack.cache.CacheManagerBinder;
 import org.dependencytrack.dex.DexEngineBinder;
 import org.dependencytrack.filters.JerseyMetricsApplicationEventListener;
 import org.dependencytrack.plugin.PluginManagerBinder;
 import org.dependencytrack.secret.SecretManagerBinder;
+import org.glassfish.hk2.utilities.binding.AbstractBinder;
 import org.glassfish.jersey.jackson.JacksonFeature;
 import org.glassfish.jersey.media.multipart.MultiPartFeature;
 
@@ -50,6 +53,15 @@ public ResourceConfig() {
         property(PROVIDER_SCANNING_RECURSIVE, true);
         property(WADL_FEATURE_DISABLE, true);
 
+        final var objectMapper = new ObjectMapper();
+        register((ContextResolver<ObjectMapper>) type -> objectMapper);
+        register(new AbstractBinder() {
+            @Override
+            protected void configure() {
+                bind(objectMapper).to(ObjectMapper.class);
+            }
+        });
+
         register(ApiFilter.class);
         register(AuthenticationFeature.class);
         register(AuthorizationFeature.class);

apiserver/src/main/java/org/dependencytrack/resources/v2/WorkflowsResource.java

@@ -19,34 +19,47 @@
 package org.dependencytrack.resources.v2;
 
 import alpine.server.auth.PermissionRequired;
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.google.protobuf.util.JsonFormat;
 import jakarta.inject.Inject;
 import jakarta.ws.rs.NotFoundException;
 import jakarta.ws.rs.Path;
 import jakarta.ws.rs.core.Response;
 import org.dependencytrack.api.v2.WorkflowsApi;
+import org.dependencytrack.api.v2.model.ListWorkflowRunEventsResponse;
+import org.dependencytrack.api.v2.model.ListWorkflowRunEventsResponseItem;
 import org.dependencytrack.api.v2.model.ListWorkflowRunsResponse;
 import org.dependencytrack.api.v2.model.SortDirection;
 import org.dependencytrack.api.v2.model.WorkflowRunStatus;
 import org.dependencytrack.auth.Permissions;
 import org.dependencytrack.common.pagination.Page;
 import org.dependencytrack.dex.engine.api.DexEngine;
+import org.dependencytrack.dex.engine.api.WorkflowRunHistoryEntry;
 import org.dependencytrack.dex.engine.api.WorkflowRunMetadata;
+import org.dependencytrack.dex.engine.api.request.ListWorkflowRunHistoryRequest;
 import org.dependencytrack.dex.engine.api.request.ListWorkflowRunsRequest;
 import org.dependencytrack.resources.AbstractApiResource;
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
+import java.io.IOException;
+import java.io.UncheckedIOException;
 import java.time.Instant;
+import java.util.Map;
+import java.util.UUID;
 
 @Path("/")
 @NullMarked
 public class WorkflowsResource extends AbstractApiResource implements WorkflowsApi {
 
     private final DexEngine dexEngine;
+    private final ObjectMapper objectMapper;
 
     @Inject
-    WorkflowsResource(DexEngine dexEngine) {
+    WorkflowsResource(DexEngine dexEngine, ObjectMapper objectMapper) {
         this.dexEngine = dexEngine;
+        this.objectMapper = objectMapper;
     }
 
     @Override
@@ -105,11 +118,7 @@ public Response listWorkflowRuns(
                             case "completed_at" -> ListWorkflowRunsRequest.SortBy.COMPLETED_AT;
                             case null, default -> null;
                         })
-                        .withSortDirection(switch (sortDirection) {
-                            case ASC -> org.dependencytrack.common.pagination.SortDirection.ASC;
-                            case DESC -> org.dependencytrack.common.pagination.SortDirection.DESC;
-                            case null -> null;
-                        })
+                        .withSortDirection(convert(sortDirection))
                         .withPageToken(pageToken)
                         .withLimit(limit));
 
@@ -123,6 +132,35 @@ public Response listWorkflowRuns(
         return Response.ok(response).build();
     }
 
+    @Override
+    @PermissionRequired({
+            Permissions.Constants.SYSTEM_CONFIGURATION,
+            Permissions.Constants.SYSTEM_CONFIGURATION_READ
+    })
+    public Response listWorkflowRunEvents(
+            UUID id,
+            @Nullable Integer fromSequenceNumber,
+            Integer limit,
+            @Nullable String pageToken,
+            @Nullable SortDirection sortDirection) {
+        final Page<WorkflowRunHistoryEntry> historyEntryPage =
+                dexEngine.listRunHistory(
+                        new ListWorkflowRunHistoryRequest(id)
+                                .withFromSequenceNumber(fromSequenceNumber)
+                                .withSortDirection(convert(sortDirection))
+                                .withPageToken(pageToken)
+                                .withLimit(limit));
+
+        final var response = ListWorkflowRunEventsResponse.builder()
+                .events(historyEntryPage.items().stream()
+                        .map(entry -> convert(entry, objectMapper))
+                        .toList())
+                .pagination(createPaginationMetadata(getUriInfo(), historyEntryPage))
+                .build();
+
+        return Response.ok(response).build();
+    }
+
     private static org.dependencytrack.dex.engine.api.@Nullable WorkflowRunStatus convert(@Nullable WorkflowRunStatus status) {
         return switch (status) {
             case CANCELLED -> org.dependencytrack.dex.engine.api.WorkflowRunStatus.CANCELLED;
@@ -170,4 +208,31 @@ private static org.dependencytrack.api.v2.model.WorkflowRunMetadata convert(Work
                 .build();
     }
 
+    private static ListWorkflowRunEventsResponseItem convert(
+            WorkflowRunHistoryEntry entry,
+            ObjectMapper objectMapper) {
+        final Map<String, Object> eventJsonMap;
+        try {
+            final String eventJson = JsonFormat.printer().print(entry.event());
+            eventJsonMap = objectMapper.readValue(eventJson, new TypeReference<>() {
+            });
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+
+        return ListWorkflowRunEventsResponseItem.builder()
+                .sequenceNumber(entry.sequenceNumber())
+                .event(eventJsonMap)
+                .build();
+    }
+
+    private static org.dependencytrack.common.pagination.@Nullable SortDirection convert(
+            @Nullable SortDirection sortDirection) {
+        return switch (sortDirection) {
+            case ASC -> org.dependencytrack.common.pagination.SortDirection.ASC;
+            case DESC -> org.dependencytrack.common.pagination.SortDirection.DESC;
+            case null -> null;
+        };
+    }
+
 }

apiserver/src/test/java/org/dependencytrack/resources/v2/WorkflowsResourceTest.java

@@ -18,17 +18,23 @@
  */
 package org.dependencytrack.resources.v2;
 
+import com.google.protobuf.util.Timestamps;
 import jakarta.ws.rs.core.Response;
 import org.dependencytrack.JerseyTestExtension;
 import org.dependencytrack.ResourceTest;
 import org.dependencytrack.auth.Permissions;
 import org.dependencytrack.common.pagination.Page;
 import org.dependencytrack.common.pagination.Page.TotalCount;
 import org.dependencytrack.common.pagination.SortDirection;
+import org.dependencytrack.dex.api.payload.PayloadConverters;
 import org.dependencytrack.dex.engine.api.DexEngine;
+import org.dependencytrack.dex.engine.api.WorkflowRunHistoryEntry;
 import org.dependencytrack.dex.engine.api.WorkflowRunMetadata;
 import org.dependencytrack.dex.engine.api.WorkflowRunStatus;
+import org.dependencytrack.dex.engine.api.request.ListWorkflowRunHistoryRequest;
 import org.dependencytrack.dex.engine.api.request.ListWorkflowRunsRequest;
+import org.dependencytrack.dex.proto.event.v1.RunCompleted;
+import org.dependencytrack.dex.proto.event.v1.WorkflowEvent;
 import org.glassfish.jersey.inject.hk2.AbstractBinder;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
@@ -43,6 +49,7 @@
 
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.dependencytrack.dex.proto.common.v1.WorkflowRunStatus.WORKFLOW_RUN_STATUS_COMPLETED;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.doReturn;
@@ -244,4 +251,60 @@ public void listWorkflowRunsShouldPassQueryParametersToDexEngine() {
         assertThat(capturedRequest.sortBy()).isEqualTo(ListWorkflowRunsRequest.SortBy.CREATED_AT);
     }
 
+    @Test
+    public void listWorkflowRunHistoryShouldReturnWorkflowRunHistory() {
+        initializeWithPermissions(Permissions.SYSTEM_CONFIGURATION_READ);
+
+        final var event = WorkflowEvent.newBuilder()
+                .setId(-1)
+                .setTimestamp(Timestamps.fromSeconds(666666))
+                .setRunCompleted(RunCompleted.newBuilder()
+                        .setStatus(WORKFLOW_RUN_STATUS_COMPLETED)
+                        .setCustomStatus("customStatus")
+                        .setResult(PayloadConverters.stringConverter().convertToPayload("payload"))
+                        .build())
+                .build();
+
+        doReturn(new Page<>(List.of(new WorkflowRunHistoryEntry(0, event)), null).withTotalCount(1, TotalCount.Type.EXACT))
+                .when(DEX_ENGINE_MOCK).listRunHistory(any(ListWorkflowRunHistoryRequest.class));
+
+        final Response response = jersey.target("/workflow-runs/de10c1ec-959e-486d-a031-deb97963ff7c/events").request()
+                .header(X_API_KEY, apiKey)
+                .get();
+        assertThat(response.getStatus()).isEqualTo(200);
+        assertThatJson(getPlainTextBody(response))
+                .isEqualTo(/* language=JSON */ """
+                        {
+                          "events": [
+                            {
+                              "sequence_number": 0,
+                              "event": {
+                                "id": -1,
+                                "timestamp": "1970-01-08T17:11:06Z",
+                                "runCompleted": {
+                                  "status": "WORKFLOW_RUN_STATUS_COMPLETED",
+                                  "customStatus": "customStatus",
+                                  "result": {
+                                    "binaryContent": {
+                                      "mediaType": "text/plain",
+                                      "data": "cGF5bG9hZA=="
+                                    }
+                                  }
+                                }
+                              }
+                            }
+                          ],
+                          "_pagination": {
+                            "links": {
+                              "self": "${json-unit.any-string}"
+                            },
+                            "total": {
+                              "count": 1,
+                              "type": "EXACT"
+                            }
+                          }
+                        }
+                        """);
+    }
+
 }