ruby_event_store-process_manager 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 459fcf11b24e60ad73c40d07162b3580da26c0a219330fa07a14a566274f1bb3
-  data.tar.gz: 8d570d1bfa61aa1f6f8d998d1003fcccf2589e46b56f18bc1f956f122915c027
+  metadata.gz: 79bc03b7d7e515cc20fdf05a7c3c4337d4f648f3acec6566874a6e09ba39da35
+  data.tar.gz: f0c2c3f704e8894be3faaca3f4650d02fd56bcf0944c9a502f29960832996425
 SHA512:
-  metadata.gz: f3dd0d8b9a41458c621dc6bce7de3f01982a321f07c5979a1246d726e9c18ab34330a203566f85d8635288984fc03fb030153d495d2d0b9d38f69a15cff4f685
-  data.tar.gz: fbe268a31631a812682d10c26370e0a853dc83b148b2b9ca8097c2fc7b33d70cb7051f01c5f935524394b27b4df049d527fed9a981c457eccd87a2ffe49e1be4
+  metadata.gz: 4e152cdc55c9b44d9569702650487eeb890352b184d4edcc1a4b118aeee8850d3cdec4b054eaa062539af4bc2a3609fd0f33ec20a4948845a18f12275bbcac6a
+  data.tar.gz: 50caa4951feadbdcf35e9e2ef64dcf646676cc57508abe523fc826d111dac85fa698e63c656c83aac162cd1e7cf2ae753d7da21d79fc150b0e1d3e5b25cf6dae

data/README.md

@@ -60,7 +60,7 @@ end
 Subscribe it to the event store:
 
 ```ruby
-process = ReleasePaymentOnOrderExpiration.new(event_store, command_bus)
+process = ReleasePaymentOnOrderExpiration.new.with(event_store:, command_bus:)
 
 event_store.subscribe(
   process,
@@ -70,6 +70,37 @@ event_store.subscribe(
 
 `fetch_id` identifies the process instance, `apply` evolves its state, and `act` issues commands based on the rebuilt state. The state class must support a no-argument constructor. `apply` must always return the next state, including for events that do not change it.
 
+A process manager class has no constructor of its own, so it can be subclassed from frameworks that instantiate it without arguments — for example a Rails `ActiveJob`, whose infrastructure calls `Job.new` with no arguments when deserializing a job:
+
+```ruby
+class ReleasePaymentOnOrderExpirationJob < ActiveJob::Base
+  include RubyEventStore::ProcessManager.with_state { ProcessState }
+
+  def perform(event)
+    with(event_store: Rails.configuration.event_store, command_bus: Rails.configuration.command_bus).call(event)
+  end
+
+  # ... fetch_id, apply, act, ProcessState as above
+end
+```
+
+Forgetting to call `with` before `call` is reported with a clear error naming the missing dependencies.
+
+## Browser integration
+
+The gem ships an extension for [RubyEventStore::Browser](https://railseventstore.org/docs/advanced-topics/browser/). Streams following the `ProcessClassName$id` naming convention get a "Process state" link, leading to a view that replays the process state step by step — showing the state after each event, next to the current state of the process.
+
+```ruby
+require "ruby_event_store/process_manager/browser_extension"
+
+RubyEventStore::Browser::App.for(
+  event_store_locator: -> { Rails.configuration.event_store },
+  extensions: [RubyEventStore::ProcessManager::BrowserExtension.new]
+)
+```
+
+The view rebuilds the state through the public `replay(events)` API every process manager exposes — it folds `apply` over the events starting from `initial_state` and returns the successive states. `act` is never invoked, so browsing the process state has no side effects.
+
 ## License
 
 MIT

data/lib/ruby_event_store/process_manager/browser_extension.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "state_replay"
+
+module RubyEventStore
+  module ProcessManager
+    class BrowserExtension
+      VIEWS_ROOT = File.expand_path("views", __dir__).freeze
+      ASSETS_ROOT = File.expand_path("public", __dir__).freeze
+
+      def views_root = VIEWS_ROOT
+
+      def assets_root = ASSETS_ROOT
+
+      def register_routes(router, context)
+        router.add_route("GET", "/process_managers/:stream_name") do |params, urls|
+          stream_name = params.fetch("stream_name")
+          process_class, process_id = ProcessManager.parse_stream_name(stream_name)
+          next context.not_found(urls) unless process_class
+
+          replay = StateReplay.new(event_store: context.event_store).call(process_class, stream_name)
+          context.render(
+            "process_managers/show",
+            urls: urls,
+            stream_name: stream_name,
+            process_class: process_class,
+            process_id: process_id,
+            steps: replay.steps,
+            current_state: replay.current_state,
+          )
+        end
+      end
+
+      def stream_links(stream_name, urls)
+        return [] unless ProcessManager.parse_stream_name(stream_name)
+
+        [{ label: "Process state", url: urls.app_url_for("process_managers", stream_name) }]
+      end
+    end
+  end
+end

data/lib/ruby_event_store/process_manager/public/ruby_event_store_process_manager.css

@@ -0,0 +1,2 @@
+/*! tailwindcss v4.3.2 | MIT License | https://tailwindcss.com */
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-border-style:solid;--tw-leading:initial;--tw-font-weight:initial}}}:root,:host{--font-mono:ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;--color-red-700:oklch(50.5% .213 27.518);--color-gray-50:oklch(98.5% .002 247.839);--color-gray-100:oklch(96.7% .003 264.542);--color-gray-400:oklch(70.7% .022 261.325);--color-gray-500:oklch(55.1% .027 264.364);--color-gray-700:oklch(37.3% .034 259.733);--color-white:#fff;--spacing:.25rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--text-sm:.875rem;--text-sm--line-height:calc(1.25 / .875);--text-2xl:1.5rem;--text-2xl--line-height:calc(2 / 1.5);--font-weight-medium:500;--font-weight-bold:700;--leading-tight:1.25}.sticky{position:sticky}.top-0{top:0}.container{width:100%}@media (min-width:40rem){.container{max-width:40rem}}@media (min-width:48rem){.container{max-width:48rem}}@media (min-width:64rem){.container{max-width:64rem}}@media (min-width:80rem){.container{max-width:80rem}}@media (min-width:96rem){.container{max-width:96rem}}.mx-auto{margin-inline:auto}.mt-1{margin-top:var(--spacing)}.mt-8{margin-top:calc(var(--spacing) * 8)}.mb-2{margin-bottom:calc(var(--spacing) * 2)}.w-full{width:100%}.cursor-help{cursor:help}.overflow-x-auto{overflow-x:auto}.overflow-x-scroll{overflow-x:scroll}.border-b{border-bottom-style:var(--tw-border-style);border-bottom-width:1px}.border-gray-50{border-color:var(--color-gray-50)}.border-gray-400{border-color:var(--color-gray-400)}.bg-white{background-color:var(--color-white)}.p-4{padding:calc(var(--spacing) * 4)}.py-4{padding-block:calc(var(--spacing) * 4)}.py-8{padding-block:calc(var(--spacing) * 8)}.pr-4{padding-right:calc(var(--spacing) * 4)}.text-left{text-align:left}.align-bottom{vertical-align:bottom}.align-top{vertical-align:top}.font-mono{font-family:var(--font-mono)}.text-2xl{font-size:var(--text-2xl);line-height:var(--tw-leading,var(--text-2xl--line-height))}.text-sm{font-size:var(--text-sm);line-height:var(--tw-leading,var(--text-sm--line-height))}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.leading-tight{--tw-leading:var(--leading-tight);line-height:var(--leading-tight)}.font-bold{--tw-font-weight:var(--font-weight-bold);font-weight:var(--font-weight-bold)}.font-medium{--tw-font-weight:var(--font-weight-medium);font-weight:var(--font-weight-medium)}.break-words{overflow-wrap:break-word}.text-gray-500{color:var(--color-gray-500)}.text-gray-700{color:var(--color-gray-700)}.text-red-700{color:var(--color-red-700)}.uppercase{text-transform:uppercase}.no-underline{text-decoration-line:none}@media (hover:hover){.hover\:bg-gray-100:hover{background-color:var(--color-gray-100)}}@media (min-width:40rem){.sm\:overflow-visible{overflow:visible}}@media (min-width:64rem){.lg\:w-12{width:calc(var(--spacing) * 12)}.lg\:w-60{width:calc(var(--spacing) * 60)}.lg\:table-fixed{table-layout:fixed}}@property --tw-border-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-leading{syntax:"*";inherits:false}@property --tw-font-weight{syntax:"*";inherits:false}

data/lib/ruby_event_store/process_manager/state_replay.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module ProcessManager
+    class StateReplay
+      Step = Struct.new(:event, :state, keyword_init: true)
+      Result = Struct.new(:steps, :current_state, keyword_init: true)
+
+      def initialize(event_store:)
+        @event_store = event_store
+      end
+
+      def call(process_class, stream_name)
+        process = process_class.new.with(event_store: @event_store, command_bus: nil)
+        events = @event_store.read.stream(stream_name).to_a
+        states = process.replay(events)
+        Result.new(
+          steps: events.zip(states).map { |event, state| Step.new(event: event, state: state) },
+          current_state: process.state,
+        )
+      end
+    end
+  end
+end

data/lib/ruby_event_store/process_manager/version.rb

@@ -2,6 +2,6 @@
 
 module RubyEventStore
   module ProcessManager
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/ruby_event_store/process_manager/views/process_managers/show.html.erb

@@ -0,0 +1,62 @@
+<div class="py-8 container mx-auto">
+  <h1 class="font-bold text-2xl">Process <%= h(process_class.name) %></h1>
+  <p class="text-gray-500 text-sm mt-1">
+    Instance <span class="font-mono font-medium text-gray-700"><%= h(process_id) %></span>,
+    state rebuilt from <a class="text-red-700 no-underline" href="<%= urls.stream_url(stream_name) %>"><%= h(stream_name) %></a>
+  </p>
+
+  <section class="mt-8">
+    <h2 class="text-gray-500 uppercase font-bold text-xs mb-2">Current state</h2>
+    <div class="overflow-x-auto">
+      <% if current_state.respond_to?(:to_h) -%>
+        <%= render("_json_tree", hash: current_state.to_h) %>
+      <% else -%>
+        <div class="font-mono text-sm"><%= h(current_state.inspect) %></div>
+      <% end -%>
+    </div>
+  </section>
+
+  <section class="mt-8">
+    <h2 class="text-gray-500 uppercase font-bold text-xs mb-2">Step by step</h2>
+    <% if steps.empty? -%>
+      <p class="text-gray-500 text-sm">No events linked to this process stream yet.</p>
+    <% else -%>
+      <div class="overflow-x-scroll sm:overflow-visible w-full">
+        <table class="w-full lg:table-fixed text-left">
+          <thead class="align-bottom leading-tight sticky top-0 bg-white text-gray-500 uppercase text-xs">
+            <tr class="border-gray-400 border-b">
+              <th class="p-4 lg:w-12">#</th>
+              <th class="py-4 pr-4">Event</th>
+              <th class="py-4 pr-4 lg:w-60"><span class="cursor-help" data-timezone-target="zone" title="UTC">Created at</span></th>
+              <th class="py-4 pr-4">State after</th>
+            </tr>
+          </thead>
+          <tbody class="align-top">
+            <% steps.to_enum.with_index(1).reverse_each do |step, number| -%>
+              <% href = urls.event_url(step.event.event_id) -%>
+              <tr class="border-gray-50 border-b hover:bg-gray-100">
+                <td class="p-4 font-mono text-sm text-gray-500"><%= number %></td>
+                <td class="py-4 pr-4">
+                  <a class="text-red-700 no-underline break-words" href="<%= href %>"><%= h(step.event.event_type) %></a>
+                  <div class="font-mono text-sm text-gray-500 break-words"><%= h(step.event.event_id) %></div>
+                </td>
+                <td class="py-4 pr-4 font-mono text-sm">
+                  <span data-timezone-target="time" data-iso="<%= step.event.metadata[:timestamp].utc.iso8601(6) %>" title="UTC"><%= step.event.metadata[:timestamp].utc.strftime("%Y-%m-%dT%H:%M:%S.%3N") %></span>
+                </td>
+                <td class="py-4 pr-4 text-sm">
+                  <div class="overflow-x-auto">
+                    <% if step.state.respond_to?(:to_h) -%>
+                      <%= render("_json_tree", hash: step.state.to_h) %>
+                    <% else -%>
+                      <span class="font-mono"><%= h(step.state.inspect) %></span>
+                    <% end -%>
+                  </div>
+                </td>
+              </tr>
+            <% end -%>
+          </tbody>
+        </table>
+      </div>
+    <% end -%>
+  </section>
+</div>

data/lib/ruby_event_store/process_manager.rb

@@ -6,28 +6,43 @@ require_relative "process_manager/retry"
 module RubyEventStore
   module ProcessManager
     module ProcessMethods
-      def initialize(event_store, command_bus)
-        @event_store = event_store
-        @command_bus = command_bus
-      end
-
       def call(event)
-        @state = initial_state
+        ensure_configured!
         @id = fetch_id(event)
         build_state(event)
         act
       end
 
+      def replay(events)
+        @state = initial_state
+        events.map { |event| @state = apply(event) }
+      end
+
+      def with(event_store:, command_bus:)
+        @event_store = event_store
+        @command_bus = command_bus
+        self
+      end
+
       private
 
       attr_reader :event_store, :command_bus, :id
 
+      def ensure_configured!
+        missing = []
+        missing << "event_store" unless @event_store
+        missing << "command_bus" unless @command_bus
+        return if missing.empty?
+
+        raise "#{self.class} is missing #{missing.join(" and ")}, call #with(event_store:, command_bus:) first"
+      end
+
       def build_state(event)
         with_retry do
           past_events = event_store.read.stream(stream_name).to_a
           last_stored = past_events.size - 1
           event_store.link(event.event_id, stream_name:, expected_version: last_stored)
-          (past_events + [event]).each { |ev| @state = apply(ev) }
+          replay(past_events + [event])
         end
       end
 
@@ -48,6 +63,22 @@ module RubyEventStore
       attr_reader :subscribed_events
     end
 
+    @registered_process_managers = {}
+
+    def self.register(process_class)
+      @registered_process_managers[process_class.name] = process_class if process_class.name
+    end
+
+    def self.parse_stream_name(stream_name)
+      class_name, _, id = stream_name.to_s.partition("$")
+      return if id.empty?
+
+      process_class = @registered_process_managers[class_name]
+      return unless process_class
+
+      [process_class, id]
+    end
+
     def self.with_state(&state_class_block)
       unless block_given?
         raise ArgumentError, "A block returning the state class is required."
@@ -61,7 +92,7 @@ module RubyEventStore
           raise "State definition block not found on #{self.class}" unless block
 
           state_class = block.call
-          raise "State definition block did not return a Class" unless state_class.is_a?(Class)
+          raise "State definition block did not return a Class" unless state_class.instance_of?(Class)
 
           state_class.new
         end
@@ -76,6 +107,7 @@ module RubyEventStore
           host_class.include(ProcessMethods)
           host_class.include(Retry)
           host_class.extend(Subscriptions)
+          ProcessManager.register(host_class)
         end
       end
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruby_event_store-process_manager
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Arkency
 bindir: bin
 cert_chain: []
-date: 2026-07-15 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_event_store
@@ -37,8 +37,12 @@ extra_rdoc_files:
 files:
 - README.md
 - lib/ruby_event_store/process_manager.rb
+- lib/ruby_event_store/process_manager/browser_extension.rb
+- lib/ruby_event_store/process_manager/public/ruby_event_store_process_manager.css
 - lib/ruby_event_store/process_manager/retry.rb
+- lib/ruby_event_store/process_manager/state_replay.rb
 - lib/ruby_event_store/process_manager/version.rb
+- lib/ruby_event_store/process_manager/views/process_managers/show.html.erb
 homepage: https://railseventstore.org
 licenses:
 - MIT
@@ -61,7 +65,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Stateful process manager with event-sourced state for RubyEventStore
 test_files: []