!!! FEATURE: Overhaul catch up implementation

[bwaidelich]

Mainly adjusts the ProjectionInterface such that the iteration of events can happen outside of the implementation.

This allows to centralize logic which enables us to:

• Support CatchUp Hooks for all core and 3rd party projections
• Improve error handling (Improve Exception handling in Projections #3854)
• Introduce a progress bar for projection replay/catchup on the CLI (Progress bar for projection replay #4200)
• Simplify projection implementation because event denormalization happens in the outer layer
• In general: Give us more control over catch ups

Breaking Change

This is a breaking change only if you implemented a custom implementation of the ProjectionInterface:

1. canHandle() now gets an instance of the domain EventInterface instead of the low level ES event

The code can be adjusted like this:

    public function canHandle(Event $event): bool
    {
        $eventClassName = $this->eventNormalizer->getEventClassName($event);
        // ...

=>

    public function canHandle(EventInterface $event): bool
    {
        $eventClassName = $event::class;
        // ...

2. catchUp() has been replaced with apply()

The code can be adjusted like this:

    public function catchUp(EventStreamInterface $eventStream, ContentRepository $contentRepository): void
    {
        // any catch up hook initialization here...
        $catchUp = CatchUp::create($this->apply(...), $this->checkpointStorage);
        $catchUp->run($eventStream);
    }

    private function apply(EventEnvelope $eventEnvelope): void
    {
        if (!$this->canHandle($eventEnvelope->event)) {
            return;
        }

        $event = $this->eventNormalizer->denormalize($eventEnvelope->event);
        // projection logic here...

=>

    public function apply(EventInterface $event): void
    {
        // projection logic here...

Note: The EventEnvelope gets passed in as 2nd argument and can be implemented if access to low-level details (e.g. event metadata) is needed:

    public function apply(EventInterface $event, EventEnvelope $eventEnvelope): void
    {
        // projection logic here...

3. getSequenceNumber() was replaced by getCheckpointStorage()

This enables the framework to use the CatchUp helper in the outer layers and it will allow us to implement better "blocking" mechanisms in the future

The code can be adjusted like this:

    public function getSequenceNumber(): SequenceNumber
    {
        return $this->checkpointStorage->getHighestAppliedSequenceNumber();
    }

=>

    public function getCheckpointStorage(): CheckpointStorageInterface
    {
        return $this->checkpointStorage;
    }

Resolves: #4289

[skurfuerst]

@bwaidelich IMHO this looks really good. Tests work still (as expected <3) So I'd say this is pretty much merge ready? (Not merging yet because the checkboxes ar enot yet ticked ;) )

[mhsdesign]

i wasnt sure what we discussed, if we now like to adapt this code style or not - but it turns out we have yet no 100% clear decision: https://neos-project.slack.com/archives/C04Q0TC15/p1692352868964289?thread_ts=1683558218.323329&cid=C04Q0TC15

[dlubitz]

This looks great. I just left some nitpic comments. 👍

[nezaniel]

Otherwise, looks great! Let's merge

[nezaniel]

Looks nice, let's do this!