I LOVE Legacy!

Learning Objectives

• Basics of Event Sourcing using an example of a library (the kind where you check out books)

 

• Three projects I have worked on and the ways we used Event Sourcing on them

Before we begin

Learning Event-Sourcing (or DDD) is tough! i

Be kind to learners (including yourself)

Event-Sourcing isn't for your whole application

Event Sourcing

The fundamental idea of Event Sourcing is that of ensuring every change to the state of an application is captured in an event object, and that these event objects are themselves stored in the sequence they were applied for the same lifetime as the application state itself.

Martin Fowler

Events and Listeners

An Event

What happened?
BookWasCheckedOut

What do I need to remember about it?
(book, patron, date)

Event Attributes

• Save only what you need to preserve
• The rest can be looked up

(book id, patron id, date)

Event Class

<?php

namespace Library\Events;

use Library\Support\Event;

class BookWasCheckedOut
{

    /**
     * @var DateTime
     */
    protected $checkoutDate;

    /**
     * @var int
     */
    protected $patronId;

    /**
     * @var int
     */
    protected $bookId;

    public function __construct(DateTime $checkoutDate, PatronId $patronId, BookId $bookId)
    {

        $this->checkoutDate = $checkoutDate;
        $this->patronId = $patronId;
        $this->bookId = $bookId;
    }

    /**
    * @return array
    */
    public function serialize()
    {
        return [
            'checkout_date' => $this->$checkoutDate->toString(),
            'patron_id' => $this->patronId->toNative(),
            'book_id' => $this->bookId->toNative(),
        ];
    }

    /**
    * @param array $data
    *
    * @return static
    */
    public static function deserialize($data)
    {
        return new BookWasCheckedOut(
            DateTime::createFromFormat('j-M-Y', $data['checkout_date']),
            PatronId::fromNative($data['patron_id']),
            BookId::fromNative($data['book_id'])
        );
    }

     /**
     * @return int
     */
    public function getBookId()
    {
        return $this->bookId;
    }

    /**
     * @return DateTime
     */
    public function getCheckoutDate(): DateTime
    {
        return $this->checkoutDate;
    }

    /**
     * @return int
     */
    public function getPatronId(): int
    {
        return $this->patronId;
    }


}

Rules for Events

• Usually named as past-tense verbs
• RARELY changed
• Never deleted
• Has attributes that are values
  • not model, object, collection, or aggregate root

Don't store objects

If We Stored Objects in an Event...

Events rarely change

• The part of the code that will change is most likely the result that follows that event.
• The structure of the resulting data is more likely to change than the thing that happened

Reasons to use Events

• State transitions are important
• We need an audit log, proof of the state we are currently in
• The history of what happened is more important than the current state
• Events are replayable if behavior in your application changes

Event Store

• Domain-specific database
• Based on a Publish-Subscribe message pattern

Projector

<?php

namespace Library\ReadModel;

use Library\Events\BookWasCheckedIn;
use Library\Events\BookWasCheckedOut;
use Library\Events\BookAddedToBookshelf;
use App\Support\ReadModel\Replayable;
use App\Support\ReadModel\SimpleProjector;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Connection;

class BookshelfProjector extends SimpleProjector implements Replayable
{

    /**
     * @var Connection
     */
    private $connection;

    /**
     * @var string table we're playing events into
     */
    private $table = 'proj_bookshelf';

    public function __construct(Connection $connection)
    {
        $this->connection = $connection;
    }

    public function beforeReplay()
    {
        $builder = $this->connection->getSchemaBuilder();

        $builder->dropIfExists('proj_bookshelf');
        $builder->create('proj_bookshelf_tmp', function (Blueprint $schema) {
            $schema->string('book_id');
            $schema->string('book_title');
            $schema->string('book_author');
            $schema->string('status');
            $schema->string('checkout_date');
            $schema->string('patron_id');

            $schema->primary('book_id');
        });

        $this->table = 'proj_bookshelf_tmp';
    }

    public function afterReplay()
    {
        $builder = $this->connection->getSchemaBuilder();

        $builder->dropIfExists('proj_bookshelf');
        $builder->rename('proj_bookshelf_tmp', 'proj_bookshelf');

        $this->table = 'proj_bookshelf';
    }

    /**
    * @param BookWasCheckedOut $event
    */
    public function applyBookWasCheckedOut(BookWasCheckedOut $event)
    {
        $bookshelfItem = BookshelfItem::where('id', $event->bookId);

        $book->status = 'Checked Out';
        $book->checkout_date = $event->checkoutDate;
        $book->patron_id = $event->patronId;

        $book->save();
    }

    /**
    * @param BookAddedToBookshelf $event
    */
    public function applyBookAddedToBookshelf(BookAddedToBookshelf $event)
    {
        $bookshelfItem = new BookshelfItem();
        $bookshelfItem->setTable($this->table);

        $bookshelfItem->bookId = $event->bookId;
        $bookshelfItem->bookTitle = $event->bookTitle;
        $bookshelfItem->bookAuthor = $event->bookAuthor;
        $bookshelfItem->status = 'on shelf';

        $bookshelfItem->save();
    }


    /**
    * @param BookWasReturned $event
    */
    public function applyBookWasReturned(BookWasReturned $event)
    {
        $bookshelfItem = BookshelfItem::where('id', $event->bookId);

        $book->status = 'Available';
        $book->checkout_date = '';
        $book->patron_id = '';

        $book->save();
    }
}

A set of event handlers that work together to build and maintain a table to be accessed by the read model.

Read Model

Read Model

<?php

namespace Library\ReadModel;


use Carbon\Carbon;
use Illuminate\Database\Eloquent\Model;

/**
* @codeCoverageIgnore
*/
class Bookshelf extends Model
{
    protected  $table = 'proj_bookshelf';
    public $incrementing = false;
    public $timestamps = false;

    public static function lookupLoansFor($patronId)
    {
        return static::where('patron_id', $patronId)->get();
    }

    public function lookupAvailableBooks()
    {
        return static::where('status', 'Available')->get();
    }

    public function lookupOverdueBooks()
    {
        return static::where('checkout_date', '<', date('Y-m-d', strtotime('-7 days')))->get();
    }
}

Creating the events

• An event is created only after validation
  • Directly in a controller 'checkout' method
  • Using a Check Out Book Command and Handler

CQRS

Command and Query Response Segregation

An application architecture pattern commonly used with event sourcing

CQRS involves splitting an application into two parts internally.

CQRS

• Command is any method that mutates state
• Query is any method that returns a value
• Should only be used on specific portions of a system, not the system as a whole

Command Handler

1. Validate the command on its own merits.
2. Validate the command on the current state of the aggregate.
3. If validation is successful, create an event(s)
4. Attempt to persist the new events. If there's a concurrency conflict during this step, retry or exit.

Command Handler example

public function update(Request $request)
    {
        // $request has book id, patron id

        try {

            $command = new CheckOutBook($request->bookId, $request->patronId);

            $this->bookLendingService->handleCheckOutBook($command);

        } catch (InvalidUserException $e) {
            return response()->json("Not authorized to check out a book.", Response::HTTP_FORBIDDEN);
        } catch (BookUnavailableException $e) {
           return response()->json("Book was not available to be checked out", 400);

    }

    <------ dynamic command handler  ------>

    private function handle(Command $command)
    {
        $method = $this->getHandleMethod($command);

        if (! method_exists($this, $method)) {
            return;
        }

        $this->$method($command);
    }

    private function getHandleMethod(Command $command)
    {
        return 'handle' . class_basename($command);
    }

    <-------- handle check out book command --------->

    public function handleCheckoutOutBook(CheckOutBook $command)
    {
        $book = Book::findOrFail($command->bookId);
        $patron = Patron::findOrFail($command->patronId);

        if (!$book->isAvailable()) {
            throw new BookUnavailableException();
        }

        if (!$patron->isAuthorized()) {
            throw new InvalidUserException();
        }

        //record the event
        $this->record(
            new BookWasCheckedOut(date("Y-m-d H:i:s"),
                $patron->getId(),
                $book->getId())
        );


    }
    

Optimize

• Separate the load from reads and writes allowing you to scale each independently.
• All commands go into a WriteService
• All queries go into a ReadService

You can choose which is best

• CRUD
• Event-Sourcing
• Event-Sourcing with CQRS
• Event-Sourcing, CQRS, DDD

My Projects

• Scholarships
• Course Registration
• Threat Reports

Flexible to Changes

• Selection Committee would never take away an award
  • until they did
• New academic year, new event store

Scholarships wrap-up

• Modernized the code in pieces
• View events from multiple contexts
• Flexible to changes in the application

Student Enrollment Process

• For Distance Education Students in the College of Engineering
• Rewrote Application
• ES to follow the process
• Status drop-down versus events

Began with Paper Forms

A lot of our systems were built to replace paper processes

They often closely map to this physical form.

© photo by Aidan Morgan

Paper Forms handling state

Status labels are like a rubber stamp

Status doesn't always communicate why or what happened

How workflows become complex

Paper Forms handling state

Piles indicate status of the form

A simple status drop-down

RECEIVED CANCELLED COURSE CANCELLED COURSE NOT APPROVED CPC DENIED CPC NOT APPROVED CPC PENDING TRANSCRIPT CPC PROCESSING DENIED DROPPED AFTER CENSUS DROPPED BEFORE CLASSES BEGUN DROPPED BETWEEN BEGINNING OF CLASS AND CENSUS DATE DROPS/WITHDRAWALS AT SITES ECE ON CAMPUS STUDENTS ENROLLMENT CANCELLED EOL APPROVED EOL MISC NEW STUDENT REGISTRATION PENDING ON CAMPUS REQUEST ON CAMPUS STUDENT NOT APPROVED PENDING CASHIER HOLD PENDING EOL APPROVAL PENDING INSTRUCTOR APPROVAL PENDING INTERNATIONAL STUDENT PENDING NDS OPEN ENROLLMENT PENDING OIS VISA STUDENT PENDING PERMANENT RESIDENT PENDING TERM ADVISEMENT HOLD PENDING TRANSCRIPT PENDING TUITION PREPAYMENT PREAPPROVED RETURNING PROCESSING NDS PROCESSING SITE PROCESSING Z PROJECT MESSAGE - MAE 586 PROJECT MESSAGE - NE 693 REGISTERED REGISTERED ASHEVILLE REGISTERED HAVELOCK REGISTERED WILMINGTON SITE APPROVAL: ASHEVILLE SITE APPROVAL: HAVELOCK SITE APPROVAL: WILMINGTON SITE NOT APPROVED SWAPPED OUT TRANSCRIPT APPROVED WITHDRAWN

A "simple" status drop-down

RECEIVED CANCELLED COURSE CANCELLED COURSE NOT APPROVED CPC DENIED CPC NOT APPROVED CPC PENDING TRANSCRIPT CPC PROCESSING DENIED DROPPED AFTER CENSUS DROPPED BEFORE CLASSES BEGUN DROPPED BETWEEN BEGINNING OF CLASS AND CENSUS DATE DROPS/WITHDRAWALS AT SITES ECE ON CAMPUS STUDENTS ENROLLMENT CANCELLED EOL APPROVED EOL MISC NEW STUDENT REGISTRATION PENDING ON CAMPUS REQUEST ON CAMPUS STUDENT NOT APPROVED PENDING CASHIER HOLD PENDING EOL APPROVAL PENDING INSTRUCTOR APPROVAL PENDING INTERNATIONAL STUDENT PENDING NDS OPEN ENROLLMENT PENDING OIS VISA STUDENT PENDING PERMANENT RESIDENT PENDING TERM ADVISEMENT HOLD PENDING TRANSCRIPT PENDING TUITION PREPAYMENT PREAPPROVED RETURNING PROCESSING NDS PROCESSING SITE PROCESSING Z PROJECT MESSAGE - MAE 586 PROJECT MESSAGE - NE 693 REGISTERED REGISTERED ASHEVILLE REGISTERED HAVELOCK REGISTERED WILMINGTON SITE APPROVAL: ASHEVILLE SITE APPROVAL: HAVELOCK SITE APPROVAL: WILMINGTON SITE NOT APPROVED SWAPPED OUT TRANSCRIPT APPROVED WITHDRAWN

Something happened

Status is a reflection of something that happened

There is ONE of each status + reasons/details

Events can record what happened

Student Enrollment Wrap-up

• Streamlined Process
• Connected the system to Student Information System
• Facilitated communication between students and admins

Analysis

Data Filtered for User Access

Inquest wrap-up

• Events created by the Engine; used in Customer-facing Site
• Events capture Session Threat History
• Optimize the results for Read, reducing time to retrieve large amounts of data
• Results are still filtered by a user's access
• Full audit log
• These events will lead to more improvements

Planned Improvements

• Fewer complex DB queries
• Could separate us from older schema; or reduce dependence on it
• Separate the logic of what an event means based on context and purpose
• Flexible to change, our interpretation of events can change, and we can rebuild projections without losing the full history

Thank you!

Emily Stamey

@elstamey

http://elstamey.com