eventsimple 1.0.0

data/app/views/eventsimple/entities/show.html.erb

@@ -0,0 +1,109 @@
+<div class="row align-items-start">
+  <!-- Pane: Entity Details Start -->
+  <div class="col g-4 col-sm-8">
+    <h2><%= @model_name%>: <%= @aggregate_id %></h2>
+    <hr/>
+
+    <ul class="nav nav-tabs" role="tablist">
+      <li class="nav-item" role="presentation">
+        <a href="#" class="nav-link action-entity-query <%= @tab_id == 'entity' ? 'active' : '' %>" id="nav-tab-entity" data-param="t" data-value="entity">Entity</a>
+      </li>
+      <li class="nav-item" role="presentation">
+        <a href="#" class="nav-link action-entity-query <%= @tab_id == 'event' ? 'active' : '' %>" id="nav-tab-event" data-param="t" data-value="event">Event</a>
+      </li>
+    </ul>
+
+    <div class="tab-content pt-4 px-3">
+      <!-- Tab: Entity Start -->
+      <div id="tab-entity" class="tab-pane <%= @tab_id == 'entity' ? 'active' : '' %>" role="tabpanel" aria-labelledby="nav-tab-entity">
+        <p>
+          Shows the changes made before and after the currently selected event was applied.
+        </p>
+        <div class="table-responsive">
+          <table class="table table-striped">
+            <thead>
+              <tr>
+                <th scope="col" width="15%"></th>
+                <th scope="col" width="25%">Before</th>
+                <th scope="col" width="25%">After</th>
+              </tr>
+            </thead>
+            <tbody>
+              <% @entity_changes.each do |property| %>
+                <tr class="<%= property[:is_changed] ? 'table-info' : '' %>">
+                  <th scope="row"><%= property[:label] %></th>
+                  <td><code class="entity-property"><%= property[:historical_value].nil? ? '-' : property[:historical_value] %></code></th>
+                  <td><code class="entity-property"><%= property[:current_value].nil? ? '-' : property[:current_value] %></code></td>
+                </tr>
+              <% end %>
+            </tbody>
+          </table>
+        </div>
+      </div>
+      <!-- Tab: Entity End -->
+
+      <!-- Tab: Event Start -->
+      <div id="tab-event" class="tab-pane <%= @tab_id == 'event' ? 'active' : '' %>" role="tabpanel" aria-labelledby="nav-tab-event">
+        <p>
+          The properties of the <code><%= @selected_event.type %></code> event.
+        </p>
+          <table class="table">
+            <tbody>
+              <tr>
+                <th scope="row">Identifier</th>
+                <td><code class="entity-property"><%= @selected_event.id %></code></td>
+              </tr>
+              <tr>
+                <th scope="row">Timestamp</th>
+                <td><code class="entity-property"><%= @selected_event.created_at %></code></td>
+              </tr>
+              <tr>
+                <th scope="row" colspan="2">Data</th>
+              </tr>
+              <% if @selected_event.data.present? %>
+                <% @selected_event.data.attributes.each do |attr_name, attr_value| %>
+                <tr>
+                  <td>&nbsp;&nbsp;&nbsp;&nbsp;<%= attr_name %></td>
+                  <td><code class="entity-property"><%= attr_value %></code></td>
+                </tr>
+                <% end %>
+              <% end %>
+              </tr>
+              <tr>
+                <th scope="row" colspan="2">Metadata</th>
+              </tr>
+              <% @selected_event.metadata.attributes.each do |attr_name, attr_value| %>
+                <tr>
+                  <td>&nbsp;&nbsp;&nbsp;&nbsp;<%= attr_name %></td>
+                  <td><code class="entity-property">: <%= attr_value %></code></td>
+                </tr>
+              <% end %>
+            </tbody>
+          </table>
+      </div>
+      <!-- Tab: Event End -->
+    </div>
+  </div>
+  <!-- Pane: Entity Details End -->
+
+  <!-- Pane: Time Travel Start -->
+  <div class="col g-4 col-sm-4">
+    <h3>Time Travel</h3>
+    <ul class="list-group">
+      <% @entity_event_history.each_with_index do | event, index | %>
+        <% is_active_list_item = event == @selected_event ? 'list-group-item-primary' : '' %>
+        <% is_active_link = event == @selected_event ? 'link-dark' : 'link-dark' %>
+        <% event_timestamp = index.zero? ? 'Current' : "#{time_ago_in_words(event.created_at)} ago"  %>
+        <li class="list-group-item <%= is_active_list_item %>">
+          <a href="#" class="text-decoration-none action-entity-query <%= is_active_link %>" data-param="e" data-value="<%= event.id %>">
+            <div class="d-flex w-100 justify-content-between">
+              <span title="<%= event.type %>" style="width: 75%; overflow: hidden; white-space: nowrap; text-overflow: ellipsis;"><%= event.type.demodulize %></span>
+              <small><%= event_timestamp %></small>
+            </div>
+          </a>
+        </li>
+      <% end %>
+    </ul>
+  </div>
+  <!-- Pane: Time Travel End -->
+</div>

data/app/views/eventsimple/models/show.html.erb

@@ -0,0 +1,19 @@
+
+<table class="table table-striped">
+  <thead>
+    <tr>
+      <th scope="col" width="15%">Time</th>
+      <th scope="col" width="30%">Identifier</th>
+      <th scope="col" width="65%">Event</th>
+    </tr>
+  </thead>
+  <tbody>
+    <% @latest_entities.each do |event| %>
+      <tr>
+        <td scope="row"><%= "#{time_ago_in_words(event.created_at)} ago" %></td>
+        <td><%= link_to event.aggregate_id, model_entity_path(@model_name, event.aggregate_id) %></td>
+        <td><%= event.type %></td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>

data/app/views/eventsimple/shared/_header.html.erb

@@ -0,0 +1,26 @@
+<!-- Header Search Start -->
+<header class="container mb-4">
+  <div class="row">
+    <div class="col col-sm-3">
+      <select id="form-search-model-name" class="form-select" aria-label="Model select" onchange="document.location.href=this.value" required>
+        <option value="">Choose event source model</option>
+        <% event_class_names.each do |klass| %>
+          <% is_active = klass === @model_name ? 'selected' : '' %>
+          <option value="<%= model_path(klass) %>" <%= is_active %>><%= klass %></option>
+        <% end %>
+      </select>
+    </div>
+
+    <% if @model_name %>
+      <div class="col col-sm-7">
+        <%= form_with url: model_entity_path(@model_name, ''), id: 'model-search' do |f| %>
+          <%= f.search_field :event_id, class: 'form-control', placeholder: 'Canonical identifier', value: @aggregate_id, required: true, aria: { label: 'Entity canonical identifier' }  %>
+        </div>
+        <div class="col col-sm-2">
+          <%= f.submit 'Search', class: 'btn btn-primary' %>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+</header>
+<!-- Header Search End -->

data/app/views/eventsimple/shared/_sidebar.html.erb

@@ -0,0 +1,19 @@
+<!-- Sidebar Nav Start -->
+<nav class="d-flex flex-column flex-shrink-0 p-3 text-white bg-dark">
+  <%= link_to root_path, class: 'd-flex align-items-center mb-3 mb-md-0 me-md-auto text-white text-decoration-none' do %>
+    <span class="fs-4">Eventsimple</span>
+  <% end %>
+  <hr>
+  <ul class="nav nav-pills flex-column mb-auto">
+    <% event_class_names.each do |klass| %>
+      <% is_active = klass === @model_name ? 'active text-white' : 'text-white' %>
+      <li class="nav-item text-white overflow-hidden" style="width: 100%;">
+        <%= link_to model_path(klass), class: "nav-link #{is_active}", style: "overflow: hidden; white-space: nowrap; text-overflow: ellipsis;" do %>
+          <i class="bi bi-table"></i>
+          <%= klass %>
+        <% end %>
+      </li>
+    <% end %>
+  </ul>
+</nav>
+<!-- Sidebar Nav End -->

data/app/views/eventsimple/shared/_style.html.erb

@@ -0,0 +1,105 @@
+  <style>
+    // Structure
+    body {
+      min-height: 100vh;
+      min-height: -webkit-fill-available;
+    }
+
+    html {
+      height: -webkit-fill-available;
+    }
+
+    #page {
+      display: flex;
+      flex-wrap: nowrap;
+      height: 100vh;
+      height: -webkit-fill-available;
+      max-height: 100vh;
+      overflow-x: auto;
+      overflow-y: hidden;
+    }
+
+    nav {
+      width: 20%;
+    }
+
+    main {
+      flex-shrink: 0;
+      height: 100vh;
+      width: 80%;
+      overflow-y: auto;
+    }
+
+    // Sidebar Nav
+
+    .bi {
+      vertical-align: -.125em;
+      pointer-events: none;
+      fill: currentColor;
+    }
+
+    .dropdown-toggle { outline: 0; }
+
+    .nav-flush .nav-link {
+      border-radius: 0;
+    }
+
+    .btn-toggle {
+      display: inline-flex;
+      align-items: center;
+      padding: .25rem .5rem;
+      font-weight: 600;
+      color: rgba(0, 0, 0, .65);
+      background-color: transparent;
+      border: 0;
+    }
+    .btn-toggle:hover,
+    .btn-toggle:focus {
+      color: rgba(0, 0, 0, .85);
+      background-color: #d2f4ea;
+    }
+
+    .btn-toggle::before {
+      width: 1.25em;
+      line-height: 0;
+      content: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='rgba%280,0,0,.5%29' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='M5 14l6-6-6-6'/%3e%3c/svg%3e");
+      transition: transform .35s ease;
+      transform-origin: .5em 50%;
+    }
+
+    .btn-toggle[aria-expanded="true"] {
+      color: rgba(0, 0, 0, .85);
+    }
+    .btn-toggle[aria-expanded="true"]::before {
+      transform: rotate(90deg);
+    }
+
+    .btn-toggle-nav a {
+      display: inline-flex;
+      padding: .1875rem .5rem;
+      margin-top: .125rem;
+      margin-left: 1.25rem;
+      text-decoration: none;
+    }
+    .btn-toggle-nav a:hover,
+    .btn-toggle-nav a:focus {
+      background-color: #d2f4ea;
+    }
+
+    .scrollarea {
+      overflow-y: auto;
+    }
+
+    .fw-semibold { font-weight: 600; }
+    .lh-tight { line-height: 1.25; }
+
+    // Styles
+
+    code {
+      color: deeppink;
+    }
+
+    code.entity-property {
+      color: #333;
+    }
+  </style>

data/app/views/layouts/eventsimple/application.html.erb

@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="">
+  <title>Eventsimple</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= stylesheet_link_tag "https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css",
+    media: "all",
+    integrity: 'sha384-rbsA2VBKQhggwzxH7pPCaAqO46MgnOM80zW1RWuH61DGLwZJEdK2Kadq2F9CUG65',
+    crossorigin: 'anonymous'
+  %>
+  <%= stylesheet_link_tag "https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.3/font/bootstrap-icons.css",
+    media: "all",
+    crossorigin: 'anonymous'
+  %>
+  <%= javascript_include_tag "https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/js/bootstrap.min.js",
+    integrity: "sha384-cuYeSxntonz0PPNlHhBs68uyIAVpIIOZZ5JqeqvYYIcEL727kskC66kF92t6Xl2V",
+    crossorigin: "anonymous"
+  %>
+  <%= javascript_include_tag "https://cdn.jsdelivr.net/npm/jquery@3.6.3/dist/jquery.min.js",
+    crossorigin: "anonymous"
+  %>
+
+  <%= render partial: 'eventsimple/shared/style' %>
+</head>
+<body>
+  <div id="page">
+    <%= render partial: 'eventsimple/shared/sidebar' %>
+
+    <!-- Main Container Start -->
+    <main class="pt-4 px-2">
+      <%= render partial: 'eventsimple/shared/header' %>
+
+      <!-- Content Start -->
+      <article class="container">
+        <% if @error_message.present? %>
+          <div class="alert alert-warning d-flex" role="alert">
+            <i class="bi bi-exclamation-triangle-fill me-2"></i>
+            <div>
+              <%= @error_message %>
+            </div>
+          </div>
+        <% else %>
+          <%= yield %>
+        <% end %>
+      </article>
+      <!-- Content End -->
+
+    </main>
+    <!-- Main Container End -->
+
+    <script>
+      $( document ).ready(() => {
+        $('.action-entity-query').click((event) => {
+          const link = $(event.currentTarget);
+          const { param, value } = link.data();
+          const query = new URLSearchParams(window.location.search)
+          query.set(param, value);
+          link.attr("href",window.location.pathname + '?' + query.toString());
+        });
+
+        $('#model-search').on('submit', (event) => {
+          event.preventDefault();
+          const form = $(event.currentTarget);
+          window.location = form.attr('action') + form.children('#event_id').val();
+        });
+      });
+    </script>
+
+  </div>
+</body>
+</html>

data/catalog-info.yaml

@@ -0,0 +1,11 @@
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: eventsimple
+  description: Event Driven Toolkit for Rails
+  tags:
+    - ruby
+spec:
+  type: library
+  lifecycle: production

data/config/routes.rb

@@ -0,0 +1,11 @@
+Eventsimple::Engine.routes.draw do
+  root to: 'home#index'
+
+  resources :models, only: [:show], param: :name do
+    member do
+      post :search
+    end
+
+    resources :entities, only: :show
+  end
+end

data/eventsimple.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "lib/eventsimple/version"
+
+Gem::Specification.new do |spec|
+  spec.name = 'eventsimple'
+  spec.version = Eventsimple::VERSION
+  spec.authors = ['Zulfiqar Ali']
+  spec.email = ['zulfiqar@wealthsimple.com']
+
+  spec.summary = 'Event driven toolkit using Rails and Sidekiq'
+  spec.description = 'Event driven architecture using Rails and Sidekiq'
+  spec.homepage = 'https://github.com/wealthsimple/eventsimple'
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata['changelog_uri'] = "https://github.com/wealthsimple/eventsimple/blob/main/CHANGELOG.md"
+  spec.license = 'MIT'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git))})
+    end
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'dry-struct', '~> 1.6'
+  spec.add_runtime_dependency 'dry-types', '~> 1.7'
+  spec.add_runtime_dependency 'pg', '~> 1.4'
+  spec.add_runtime_dependency 'rails', '~> 7.0'
+  spec.add_runtime_dependency 'retriable', '~> 3.1'
+  spec.add_runtime_dependency 'sidekiq', '~> 7.0'
+
+  spec.add_development_dependency 'bundle-audit'
+  spec.add_development_dependency 'fuubar'
+  spec.add_development_dependency 'git'
+  spec.add_development_dependency 'guard-rspec'
+  spec.add_development_dependency 'parse_a_changelog'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'puma'
+  spec.add_development_dependency 'rspec-rails'
+  spec.add_development_dependency 'ws-style'
+end

data/lib/dry_types.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DryTypes
+  include Dry.Types()
+end

data/lib/eventsimple/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Eventsimple
+  class Configuration
+    attr_reader :max_concurrency_retries, :dispatchers
+    attr_writer :metadata_klass
+
+    attr_accessor :ui_visible_models
+
+    def initialize
+      @dispatchers = []
+      @max_concurrency_retries = 2
+      @metadata_klass = 'Eventsimple::Metadata'
+
+      @ui_visible_models = [] # internal use only
+    end
+
+    def max_concurrency_retries=(value)
+      unless value.is_a?(Integer) && value.positive?
+        raise ArgumentError, 'max_concurrency_retries must be a positive integer'
+      end
+
+      @max_concurrency_retries = value
+    end
+
+    def dispatchers=(value)
+      raise ArgumentError, 'dispatchers must be an array' unless value.is_a?(Array)
+
+      @dispatchers = value
+    end
+
+    def metadata_klass
+      @klass ||= @metadata_klass.constantize # rubocop:disable Naming/MemoizedInstanceVariableName
+    end
+  end
+end

data/lib/eventsimple/data_type.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Eventsimple
+  class DataType < ActiveModel::Type::Value
+    def initialize(event_klass)
+      @event_klass = event_klass
+      super()
+    end
+
+    attr_reader :event_klass
+
+    def type
+      :data_type
+    end
+
+    def cast_value(value)
+      case value
+      when String
+        decoded = ActiveSupport::JSON.decode(value)
+        return event_klass::Message.new(decoded) if event_klass.const_defined?(:Message)
+
+        decoded
+      when Hash
+        return event_klass::Message.new(value) if event_klass.const_defined?(:Message)
+
+        value
+      when event_klass::Message
+        value
+      end
+    end
+
+    def serialize(value)
+      case value
+      when Hash, event_klass::Message
+        ActiveSupport::JSON.encode(value)
+      else
+        super
+      end
+    end
+
+    def deserialize(value)
+      decoded = ActiveSupport::JSON.decode(value)
+      return event_klass::Message.new(decoded) if event_klass.const_defined?(:Message)
+
+      decoded
+    end
+  end
+end

data/lib/eventsimple/dispatcher.rb

@@ -0,0 +1,17 @@
+module Eventsimple
+  class Dispatcher
+    def self.on(*events, sync: [], async: [])
+      # Register Reactors to Events.
+      # * Reactors registered with `sync` will be synced synchronously
+      # * Reactors registered with `async` will be synced asynchronously via a Sidekiq Job
+      #
+      # Example:
+      #
+      #   on BaseEvent, sync: LogEvent, async: TrackEvent
+      #   on PledgeCancelled, PaymentFailed, async: [NotifyAdmin, CreateTask]
+      #   on [PledgeCancelled, PaymentFailed], async: [NotifyAdmin, CreateTask]
+      #
+      EventDispatcher.rules.register(events: events.flatten, sync: Array(sync), async: Array(async))
+    end
+  end
+end

data/lib/eventsimple/engine.rb

@@ -0,0 +1,37 @@
+require 'rails'
+
+module Eventsimple
+  class Engine < ::Rails::Engine
+    isolate_namespace Eventsimple
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.helper false
+      g.view_specs false
+    end
+
+    config.after_initialize do
+      dispatchers = Eventsimple.configuration.dispatchers.map(&:constantize)
+
+      unless dispatchers.all? { |dispatcher| dispatcher.superclass == Eventsimple::Dispatcher }
+        raise ArgumentError, 'dispatchers must inherit from Eventsimple::Dispatcher'
+      end
+
+      retry_intervals = Array.new(Eventsimple.configuration.max_concurrency_retries) { 0 }
+
+      Retriable.configure do |c|
+        c.contexts[:reactor] = {
+          tries: 7,
+          base_interval: 1.0,
+          multiplier: 1.0,
+          rand_factor: 0.0,
+          on: ActiveRecord::RecordNotFound,
+        }
+        c.contexts[:optimistic_locking] = {
+          intervals: retry_intervals,
+          on: ActiveRecord::StaleObjectError,
+        }
+      end
+    end
+  end
+end

data/lib/eventsimple/entity.rb

@@ -0,0 +1,54 @@
+module Eventsimple
+  module Entity
+    DEFAULT_IGNORE_PROPS = %w[id lock_version].freeze
+
+    def event_driven_by(event_klass, aggregate_id:)
+      has_many :events, class_name: event_klass.name.to_s,
+        foreign_key: :aggregate_id,
+        primary_key: aggregate_id,
+        dependent: :delete_all,
+        inverse_of: model_name.element.to_sym,
+        autosave: false,
+        validate: false
+
+      class_attribute :ignored_for_projection, default: []
+
+      # disable automatic timestamp updates
+      self.record_timestamps = false
+
+      Eventsimple.configuration.ui_visible_models |= [self]
+
+      include InstanceMethods
+      extend ClassMethods
+    end
+
+    module InstanceMethods
+      def projection_matches_events?
+        reprojected = self.class.find(id).reproject
+
+        attributes == reprojected.attributes
+      end
+
+      def reproject(at: nil)
+        event_history = at ? events.where('created_at <= ?', at).load : events.load
+        ignore_props = (DEFAULT_IGNORE_PROPS + ignored_for_projection).map(&:to_s)
+        assign_attributes(self.class.column_defaults.except(*ignore_props))
+
+        event_history.each do |event|
+          event.apply(self)
+          event.apply_timestamps(self)
+        end
+
+        self
+      end
+    end
+
+    module ClassMethods
+      def event_class
+        reflect_on_all_associations(:has_many).find { |association|
+          association.name == :events
+        }.klass
+      end
+    end
+  end
+end