Expose event publications via actuator

[odrotbohm]

[tobHai]

Hi @odrotbohm!

I would like to implement this feature.

I assume this functionality should be implemented in a new submodule of spring-modulith-events, e.g spring-modulith-events-actuator.
Is that correct?

[odrotbohm]

That's appreciated. I was thinking of an addition to the already existing spring-modulith-actuator with an optional dependency on the events artifacts and autoconfiguration registering the components based on the ultimate classpath arrangement.

I'd suggest basing your work on top of the feature/796-epr2 branch as that's what's going to be the state model for 2.0 going forward. It would be nice to see the new state model (published, in process, failed, resubmitted) reflected in the API exposed. Maybe it makes sense to iterate a bit on the design of the resource(s) to be exposed here first?

[tobHai]

Sure, I would appreciate that!

Do you already have a path in mind? Should the endpoint be available under the actuator/modulith path?
Maybe actuator/modulith/events ?

Should the endpoint return something like:

{
   "counts": {
      "published": 10,
      ....
   }
}

This way new statuses can be easily added later on.
Furthermore, other event related data could be added as a new key in the endpoint.
Or do you have a different structure in mind?

[odrotbohm]

I'd start with a new endpoint eventpublications (under /actuator/eventpublications{?status}) that lists the event publications as JSON.

{
  "_embedded" : {
    "eventPublications" :  [ <- for each, filtered by optional status
      {
        "id" : "4711",
        "publicationDate" : "…",
        "status" : "failed",
        …,
        "_links" : {
          "self" : {
            "href" : "/actuator/event-publications/4711"
          }
          "resubmit" : { <- only present for publications of status 'failed'
            "href" : "/actuator/event-publications/4711/resubmit"
          }
        }
        "_templates" { <- only present for publications of status 'failed'
          "resubmit" : {
            "title" : "Resubmit publication",
            "method" : "POST"
          }
        }
      },
      …
    ]
  }
  "_templates" : {
    "all-publications" : {
      "title" : "All publications",
      "method" : "GET",
      "properties" : [
        {
          "name" : "status",
          "prompt" : "Status",
          "options" : {
            "inline" : [
              { "prompt" : "Published", "value" : "published" },
              { "prompt" : "Processing", "value" : "processing" },
              { "prompt" : "Completed", "value" : "completed" },
              { "prompt" : "Failed", "value" : "failed" },
              { "prompt" : "Resubmitted", "value" : "resubmitted" }
            ]
          }
        }
      ]
    }
  }
}

The suggested structure could be implemented using this endpoint skeleton:

@Endpoint("eventpublications")
class EventPublicationsActuator {
  
  @ReadOperation
  String listPublications(@OptionalParameter String status) {

  }

  @ReadOperation
  String showPublication(@Selector UUID id) {

  }

  @WriteOperation
  void resubmitApplication(@Selector(match = Match.ALL_REMAINING) String[] segments) {
    // 1. -> Publication ID
    // 2. "resubmit"
  }
}

Open questions

• Instead of a status request parameter, does it make sense to rather expose dedicated resources per status? That'd help with batching, too.
• Default sorting? Latest (by publication date) first? Oldest first?
• Which statuses to include if no parameter value is given? Does it make sense to default to only include non-failed publications by default as that reduces the risk of having to return too many publications at once?
• At some point, we're going to need pagination.

[tobHai]

Thanks for the detailed draft!

A few more questions regarding the implementation:
Would it be fine to work with the EventPublicationRepository directly in the endpoint?
If so I think, we would need a new method to fetch a single event publication via ID.

Regarding the default sorting: I assume both options have their valid use cases.
Clients might be interested in the oldest failed event publications to resubmit them first but seeing the latest published event publication could also be a valid use case?

Does it make sense to default to only include non-failed publications by default as that reduces the risk of having to return too many publications at once?
Shouldn't that be usual the other way around? I could imagine that during "normal operations" the number of non-failed publications exceed the failed ones? But that assumption can be wrong of course 😄