Part VII - The Unhappy Path

Developers tend to work out the happy path of a feature only and throw exceptions in every unknown situation. This behaviour is often caused by bad project management. Developers get domain knowledge from Jira tickets written by a product owner (Jira is used here as a synonym for any ticket system used in an agile process) instead of talking to domain experts face-to-face. Most tickets don't include unhappy paths until they happen and find their way back to the developer as a bug ticket.

Is this really the best way to deal with unexpected scenarios? Wouldn't it be better to prepare for the unhappy paths as well? Sure, it takes more time upfront but saves a lot of time later when the application runs in production and can deal with failure scenarios in a sane way.

Our Building aggregate does a bad job with regards to failure handling. Imagine a user is already in a building and tries to check in again. What does that mean in the real world? First of all it is not possible to be in and out of a building at the same time. So either a hacker has stolen the identity or system state is broken for whatever reason. Deciding if entrance to the building is blocked or not should be made by the business. And regardless of the decision it is always interesting to have an event in the event stream about the double check in. This makes monitoring much simpler than scanning error logs.

We've talked to the domain experts and they want us to notify security in case of a DoubleCheckIn. With Event Machine this is as simple as throwing an exception ;)

We need an event to record a DoubleCheckIn:

<?php

declare(strict_types=1);

namespace App\Api;

use Prooph\EventMachine\EventMachine;
use Prooph\EventMachine\EventMachineDescription;
use Prooph\EventMachine\JsonSchema\JsonSchema;

class Event implements EventMachineDescription
{
    const BUILDING_ADDED = 'BuildingAdded';
    const USER_CHECKED_IN = 'UserCheckedIn';
    const DOUBLE_CHECK_IN_DETECTED = 'DoubleCheckInDetected';

    /**
     * @param EventMachine $eventMachine
     */
    public static function describe(EventMachine $eventMachine): void
    {
        /* ... */

        $eventMachine->registerEvent(
            self::DOUBLE_CHECK_IN_DETECTED,
            JsonSchema::object([
                Payload::BUILDING_ID => Schema::buildingId(),
                Payload::NAME => Schema::username(),
            ])
        );
    }
}

Now that we have the event we can replace the exception and yield a DoubleCheckInDetected event instead:

<?php

declare(strict_types=1);

namespace App\Model;

use App\Api\Event;
use App\Api\Payload;
use Prooph\EventMachine\Messaging\Message;

final class Building
{
    public static function add(Message $addBuilding): \Generator
    {
        yield [Event::BUILDING_ADDED, $addBuilding->payload()];
    }

    public static function whenBuildingAdded(Message $buildingAdded): Building\State
    {
        return Building\State::fromArray($buildingAdded->payload());
    }

    public static function checkInUser(Building\State $state, Message $checkInUser): \Generator
    {
        if($state->isUserCheckedIn($checkInUser->get(Payload::NAME))) {
            yield [Event::DOUBLE_CHECK_IN_DETECTED, $checkInUser->payload()];
            return; //<-- Note: we need to return, otherwise UserCheckedIn would be yielded, too
        }

        yield [Event::USER_CHECKED_IN, $checkInUser->payload()];
    }

    public static function whenUserCheckedIn(Building\State $state, Message $userCheckedIn): Building\State
    {
        return $state->withCheckedInUser($userCheckedIn->get(Payload::NAME));
    }

    public static function whenDoubleCheckInDetected(Building\State $state, Message $event): Building\State
    {
        //No state change required, simply return current state
        return $state;
    }
}

We need to tell Event Machine that Building::checkInUser() yields DoubleCheckInDetected in some situations:

<?php

declare(strict_types=1);

namespace App\Api;

use App\Model\Building;
use Prooph\EventMachine\EventMachine;
use Prooph\EventMachine\EventMachineDescription;

class Aggregate implements EventMachineDescription
{
    const BUILDING = 'Building';


    /**
     * @param EventMachine $eventMachine
     */
    public static function describe(EventMachine $eventMachine): void
    {
        /* ... */

        $eventMachine->process(Command::CHECK_IN_USER)
            ->withExisting(self::BUILDING)
            ->handle([Building::class, 'checkInUser'])
            ->recordThat(Event::USER_CHECKED_IN)
            ->apply([Building::class, 'whenUserCheckedIn'])
            ->orRecordThat(Event::DOUBLE_CHECK_IN_DETECTED)
            ->apply([Building::class, 'whenDoubleCheckInDetected']);
    }
}

Try to check John in again:

{
  "payload": {
    "buildingId": "9ee8d8a8-3bd3-4425-acee-f6f08b8633bb",
    "name": "John"
  }
}

Instead of an error we get a 202 command accepted response.

But when we look at the event stream (table _4228e4a00331b5d5e751db0481828e22a2c3c8ef) we see a DoubleCheckInDetected event.

Process Manager

To complete the user story we have to notify security. The security team uses a dedicated monitoring application that can receive arbitrary notification messages. To communicate with that external system we can use a so-called process manager or policy. Maybe you're more familiar with the term event listener but be careful to not mix it with event listeners known from web frameworks like Symfony or Zend. Listeners in Event Machine react to domain events and trigger follow up commands for actions, like sending emails or interacting with external systems.

We can simulate the security monitoring system with a small JS app shipped with the event-machine-skeleton. Open http://localhost:8080/ws.html in your browser.

Note: If the app shows a connection error then try to log into the rabbit mgmt console first: https://localhost:8081. Accept the self-signed certificate and login with usr: prooph pwd: prooph. If you're logged in switch back to http://localhost:8080/ws.html and reload the page.

If the app says Status: Connected to websocket: ui-queue it is ready to receive messages from Event Machine.

In src/Service/ServiceFactory you can find a factory method for a App\Infrastructure\ServiceBus\UiExchange. It's a default domain event listener shipped with the skeleton that can be used to push events on a RabbitMQ ui-exchange. The exchange is preconfigured (you can see that in the rabbit mgmt UI) and the JS app connects to a corresponding ui-queue.

In src/Api/Listener we can put together the pieces:

<?php

declare(strict_types=1);

namespace App\Api;

use App\Infrastructure\ServiceBus\UiExchange;
use Prooph\EventMachine\EventMachine;
use Prooph\EventMachine\EventMachineDescription;

class Listener implements EventMachineDescription
{

    public static function describe(EventMachine $eventMachine): void
    {
        $eventMachine->on(Event::DOUBLE_CHECK_IN_DETECTED, UiExchange::class);
    }
}

Whenever a DoubleCheckInDetected event is recorded and written to the stream Event Machine invokes the UiExchange listener that takes the event and pushes it to rabbit.

Try to check John in again, while keeping an eye on the monitoring app http://localhost:8080/ws.html.

{
  "payload": {
    "buildingId": "9ee8d8a8-3bd3-4425-acee-f6f08b8633bb",
    "name": "John"
  }
}

]

The End

Congratulations! You've mastered the Event Machine tutorial. There are two bonus parts available to learn more about custom projections and testing with Event Machine. And another two bonus parts introduce Event Machine Flavours. Choose your own Flavour and maximize your very personal developer experience with Event Machine.

The current implementation is available as a demo branch of proophsoftware/event-machine-skeleton.

The Event Machine API docs contain a lot more details. Last but not least, a reminder that the prooph software team offers commercial project support and workshops for Event Machine and the prooph components.

Our workshops include Event Storming sessions and guidance on how to turn the results into working prototypes using Event Machine. We can also show and discuss framework integrations. Event Machine can easily be integrated with Symfony, Laravel and other PHP web frameworks. The skeleton is based on Zend Strategility so you can handle http related tasks, like authentication, using PSR-15 middleware. But again, other web frameworks play nicely with Event Machine, too.

If you are interested please get in touch!