event_engine 0.1.0 → 0.2.0

data/Rakefile

@@ -8,5 +8,4 @@ require "bundler/gem_tasks"
 task test: "app:test"
 task default: :test
 
-require "event_engine/the_local"
 require "the_local/rake"

data/lib/event_engine/catalog_entry.rb

@@ -0,0 +1,84 @@
+require "digest"
+require "json"
+
+module EventEngine
+  class CatalogEntry < Struct.new(
+    :event_name,
+    :event_version,
+    :event_type,
+    :subject,
+    :domain,
+    :required_inputs,
+    :optional_inputs,
+    :payload_fields,
+    keyword_init: true
+  )
+
+    def self.from_h(hash)
+      h = hash.transform_keys(&:to_sym)
+
+      new(
+        event_name: h[:event_name]&.to_sym,
+        event_version: h[:event_version],
+        event_type: h[:event_type]&.to_sym,
+        subject: h[:subject]&.to_sym,
+        domain: h[:domain]&.to_sym,
+        required_inputs: Array(h[:required_inputs]).map(&:to_sym),
+        optional_inputs: Array(h[:optional_inputs]).map(&:to_sym),
+        payload_fields: Array(h[:payload_fields]).map { |field| payload_field_from_h(field) }
+      )
+    end
+
+    def self.payload_field_from_h(field)
+      f = field.transform_keys(&:to_sym)
+
+      {
+        name: f[:name]&.to_sym,
+        required: f[:required],
+        from: f[:from]&.to_sym,
+        attr: f[:attr]&.to_sym
+      }
+    end
+
+    def fingerprint
+      Digest::SHA256.hexdigest(canonical_representation)
+    end
+
+    def to_h
+      {
+        event_name: event_name,
+        event_version: event_version,
+        event_type: event_type,
+        subject: subject,
+        domain: domain,
+        required_inputs: required_inputs,
+        optional_inputs: optional_inputs,
+        payload_fields: payload_fields.map { |field| payload_field_h(field) },
+        fingerprint: fingerprint
+      }
+    end
+
+    private
+
+    def canonical_representation
+      {
+        event_name: event_name.to_s,
+        event_type: event_type.to_s,
+        required_inputs: required_inputs.map(&:to_s).sort,
+        optional_inputs: optional_inputs.map(&:to_s).sort,
+        payload_fields: payload_fields
+          .map { |h| h.transform_values { |v| v.to_s } }
+          .sort_by { |h| h[:name].to_s }
+      }.to_json
+    end
+
+    def payload_field_h(field)
+      {
+        name: field[:name],
+        from: field[:from],
+        attr: field[:attr],
+        required: field[:required]
+      }
+    end
+  end
+end

data/lib/event_engine/configuration.rb

@@ -1,20 +1,20 @@
 module EventEngine
-  # Holds configuration options for EventEngine core.
-  #
-  # @example
-  #   EventEngine.configure do |config|
-  #     config.logger = Rails.logger
-  #   end
   class Configuration
-    # @!attribute [rw] logger
-    #   Logger instance for EventEngine messages.
-    #   @return [Logger] defaults to +Rails.logger+
     attr_accessor :logger
 
     attr_accessor :metadata_defaults
 
+    attr_accessor :schema_path
+
+    attr_accessor :rules_path
+
+    attr_accessor :publisher_schema_paths
+
     def initialize
       @logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+      @schema_path = "db/event_schema.json"
+      @rules_path = "config/event_rules.yml"
+      @publisher_schema_paths = []
     end
   end
 end

data/lib/event_engine/definition_publisher.rb

@@ -0,0 +1,22 @@
+module EventEngine
+  class DefinitionPublisher
+    class EventNotInCatalogError < StandardError; end
+
+    def publish(event_name, domain:, inputs:, **envelope)
+      EventEngine.emit(event_name, domain: domain, inputs: inputs, **envelope)
+    rescue SchemaRegistry::UnknownEventError
+      raise EventNotInCatalogError, missing_event_message(event_name, domain)
+    end
+
+    private
+
+    def missing_event_message(event_name, domain)
+      <<~MSG
+        EventEngine has no schema for #{event_name} in domain #{domain.inspect}.
+
+        Its pack's schema.json is missing from the committed catalog. Rebuild it with:
+          bin/rails event_engine:catalog
+      MSG
+    end
+  end
+end

data/lib/event_engine/event.rb

@@ -1,7 +1,4 @@
 module EventEngine
-  # A non-persisted, in-memory representation of an emitted event with a
-  # symbol-keyed payload. Passed to subscribers' +#handle(event)+ at every
-  # in-process level (1-3), and returned by the emitter for levels 1 and 2.
   Event = Struct.new(
     :event_name,
     :event_type,
@@ -18,11 +15,6 @@ module EventEngine
     :aggregate_version,
     keyword_init: true
   ) do
-    # Builds an Event from a record responding to the same members (e.g. an
-    # OutboxEvent), normalizing the payload to symbol keys.
-    #
-    # @param record [#payload]
-    # @return [Event]
     def self.from(record)
       attrs = members.to_h { |member| [member, record.public_send(member)] }
       attrs[:payload] = attrs[:payload].to_h.transform_keys(&:to_sym)

data/lib/event_engine/event_builder.rb

@@ -1,13 +1,5 @@
 module EventEngine
-  # Constructs an event payload hash from a schema and input data.
-  # Validates that required inputs are present and no unknown inputs are passed.
   class EventBuilder
-    # Builds an event attributes hash from schema and input data.
-    #
-    # @param schema [EventDefinition::Schema] the event schema
-    # @param data [Hash] input data keyed by input name
-    # @return [Hash] event attributes including :event_name, :event_type, :event_version, :payload
-    # @raise [ArgumentError] if required inputs are missing or unknown inputs are provided
     def self.build(schema:, data:)
       validate_inputs!(schema, data)
 

data/lib/event_engine/event_schema.rb

@@ -1,87 +1,53 @@
 module EventEngine
-  # Container for all event schemas, organized by event name and version.
-  # This is the data structure loaded from the compiled +db/event_schema.rb+ file
-  # and used by {SchemaRegistry} at runtime.
   class EventSchema
     class DuplicateEventNameError < StandardError; end
 
-    # Creates an EventSchema using a block DSL (used by the schema file).
-    #
-    # @yieldparam schema [EventSchema]
-    # @return [EventSchema]
-    def self.define(&block)
-      schema = new
-      block.call(schema)
-      schema
-    end
-
     def initialize
       @schemas_by_event = {}
       @finalized = false
     end
 
-    # Registers a schema for a specific event name and version.
-    #
-    # @param schema [EventDefinition::Schema]
-    # @raise [FrozenError] if the schema has been finalized
     def register(schema)
       raise FrozenError, "EventSchema is finalized" if @finalized
-      event_name = schema.event_name
+      key = key_for(schema.domain, schema.event_name)
       version = schema.event_version
 
-      @schemas_by_event[event_name] ||= {}
-      guard_duplicate_event_name!(@schemas_by_event[event_name][version], schema)
-      @schemas_by_event[event_name][version] = schema
+      @schemas_by_event[key] ||= {}
+      guard_duplicate_event_name!(@schemas_by_event[key][version], schema)
+      @schemas_by_event[key][version] = schema
     end
 
     def guard_duplicate_event_name!(existing, incoming)
       return unless existing
 
       raise DuplicateEventNameError,
-            "duplicate event_name #{incoming.event_name.inspect}: " \
-            "already registered with domain #{existing.domain.inspect}, " \
-            "cannot register again with domain #{incoming.domain.inspect}"
+            "duplicate (domain, event_name) " \
+            "(#{incoming.domain.inspect}, #{incoming.event_name.inspect}): " \
+            "already registered at version #{existing.event_version.inspect}"
     end
 
-    # Returns all registered event names.
-    #
-    # @return [Array<Symbol>]
-    def events
+    def events(domain: nil)
       @schemas_by_event.keys
+        .select { |(schema_domain, _name)| domain.nil? || schema_domain == domain }
+        .map { |(_domain, event_name)| event_name }
+        .uniq
     end
 
-    # Returns sorted version numbers for a given event.
-    #
-    # @param event_name [Symbol]
-    # @return [Array<Integer>]
-    def versions_for(event_name)
-      versions = @schemas_by_event[event_name]
-      return [] unless versions
-      versions.keys.sort
+    def versions_for(event_name, domain: nil)
+      version_sets_for(event_name, domain).flat_map(&:keys).uniq.sort
     end
 
-    # Returns the schema for a specific event name and version.
-    #
-    # @param event_name [Symbol]
-    # @param version [Integer]
-    # @return [EventDefinition::Schema, nil]
-    def schema_for(event_name, version)
-      @schemas_by_event.dig(event_name, version)
+    def schema_for(event_name, version, domain: nil)
+      set = version_sets_for(event_name, domain).find { |versions| versions.key?(version) }
+      set && set[version]
     end
 
-    # Returns the latest (highest version) schema for an event.
-    #
-    # @param event_name [Symbol]
-    # @return [EventDefinition::Schema, nil]
-    def latest_for(event_name)
-      versions = @schemas_by_event[event_name]
-      return nil unless versions && !versions.empty?
-      versions[versions.keys.max]
+    def latest_for(event_name, domain: nil)
+      merged = version_sets_for(event_name, domain).reduce({}, :merge)
+      return nil if merged.empty?
+      merged[merged.keys.max]
     end
 
-    # Freezes the schema, preventing further registrations.
-    #
-    # @return [void]
     def finalize!
       @finalized = true
       @schemas_by_event.each_value(&:freeze)
@@ -89,11 +55,20 @@ module EventEngine
       freeze
     end
 
-    # Returns the internal hash of schemas keyed by event name and version.
-    #
-    # @return [Hash{Symbol => Hash{Integer => EventDefinition::Schema}}]
     def schemas_by_event
       @schemas_by_event
     end
+
+    private
+
+    def key_for(domain, event_name)
+      [domain, event_name]
+    end
+
+    def version_sets_for(event_name, domain = nil)
+      @schemas_by_event.select do |(schema_domain, name), _versions|
+        name == event_name && (domain.nil? || schema_domain == domain)
+      end.values
+    end
   end
 end

data/lib/event_engine/event_schema_json_loader.rb

@@ -0,0 +1,19 @@
+require "json"
+
+module EventEngine
+  class EventSchemaJsonLoader
+    def self.load(path)
+      registry = SchemaRegistry.new
+      return registry unless File.exist?(path)
+
+      contents = File.read(path.to_s)
+      return registry if contents.strip.empty?
+
+      JSON.parse(contents).each do |attributes|
+        registry.register(CatalogEntry.from_h(attributes))
+      end
+
+      registry
+    end
+  end
+end

data/lib/event_engine/handler_registry.rb

@@ -4,14 +4,14 @@ module EventEngine
       @handlers = []
     end
 
-    def register(handler, levels:)
-      @handlers << { handler: handler, levels: levels }
+    def register(handler, process_types:)
+      @handlers << { handler: handler, process_types: process_types }
     end
 
     def dispatch(event)
       @handlers.each do |registration|
-        levels = registration[:levels]
-        registration[:handler].call(event) if levels == :all || levels.include?(event.process_type)
+        process_types = registration[:process_types]
+        registration[:handler].call(event) if process_types == :all || process_types.include?(event.process_type)
       end
       event
     end

data/lib/event_engine/invalid_rules_error.rb

@@ -0,0 +1,8 @@
+module EventEngine
+  class InvalidRulesError < StandardError
+    def initialize(names)
+      super("the rules file names #{names.map(&:inspect).join(", ")}, " \
+            "but no processor is registered under #{names.one? ? "that name" : "those names"}")
+    end
+  end
+end

data/lib/event_engine/processing_rules.rb

@@ -0,0 +1,39 @@
+require "yaml"
+
+module EventEngine
+  class ProcessingRules
+    def self.load(path)
+      return new unless File.exist?(path.to_s)
+
+      contents = YAML.safe_load_file(path.to_s) || {}
+
+      new(
+        default: contents["default"]&.to_sym,
+        packs: symbolize(contents["packs"]),
+        events: symbolize(contents["events"])
+      )
+    end
+
+    def self.symbolize(section)
+      (section || {}).to_h { |key, value| [ key.to_sym, value&.to_sym ] }
+    end
+
+    def initialize(default: nil, packs: {}, events: {})
+      @default = default
+      @packs = packs
+      @events = events
+    end
+
+    def for(event_name:, pack:)
+      @events[event_name] || @packs[pack] || @default
+    end
+
+    def any?
+      !@default.nil? || @packs.any? || @events.any?
+    end
+
+    def processor_names
+      ([ @default ] + @packs.values + @events.values).compact.uniq
+    end
+  end
+end

data/lib/event_engine/processor_registry.rb

@@ -0,0 +1,19 @@
+module EventEngine
+  class ProcessorRegistry
+    def initialize
+      @processors = {}
+    end
+
+    def register(name, processor)
+      @processors[name] = processor
+    end
+
+    def fetch(name)
+      @processors[name]
+    end
+
+    def clear!
+      @processors.clear
+    end
+  end
+end

data/lib/event_engine/processor_resolver.rb

@@ -0,0 +1,16 @@
+module EventEngine
+  class ProcessorResolver
+    def initialize(rules)
+      @rules = rules
+    end
+
+    def routes?
+      @rules.any?
+    end
+
+    def resolve(event)
+      @rules.for(event_name: event.event_name, pack: event.domain) ||
+        raise(UnroutableEventError.new(event))
+    end
+  end
+end

data/lib/event_engine/railtie.rb

@@ -1,9 +1,59 @@
 module EventEngine
-  class Railtie < Rails::Railtie
+  class Railtie < ::Rails::Railtie
     rake_tasks do
-      load "tasks/event_engine_tasks.rake"
-      load "tasks/event_engine_schema.rake"
-      load "tasks/event_engine_schema_check.rake"
+      Dir[File.expand_path("../tasks/*.rake", __dir__)].sort.each { |task| load task }
+    end
+
+    initializer "event_engine.load_schema_and_helpers" do |app|
+      EventEngine.configuration.schema_path = Rails.root.join("db", "event_schema.json").to_s
+
+      app.config.after_initialize do
+        schema_path = Rails.root.join("db", "event_schema.json")
+        helpers_path = Rails.root.join("db", "event_engine_helpers.rb")
+
+        if File.exist?(schema_path)
+          Railtie.send(:boot!, schema_path: schema_path, helpers_path: helpers_path)
+        else
+          Railtie.send(:handle_missing_schema!, schema_path)
+        end
+
+      end
+    end
+
+    class << self
+      private
+
+      def boot!(schema_path:, helpers_path:)
+        EventEngine.register_definition_publisher!
+
+        EventEngine.boot_from_schema!(
+          schema_path: schema_path,
+          registry: EventEngine::SchemaRegistry.new
+        )
+
+        load helpers_path if File.exist?(helpers_path)
+      end
+
+      def handle_missing_schema!(schema_path)
+        if Rails.env.development? || Rails.env.test?
+          Rails.logger.warn(
+            "[EventEngine] Schema catalog not found at #{schema_path}. " \
+            "Commit it, or build it from your packs' schema.json with: " \
+            "bin/rails event_engine:catalog"
+          )
+          return
+        end
+
+        raise <<~MSG
+          EventEngine schema catalog missing.
+
+          Expected to find:
+            #{schema_path}
+
+          Commit the catalog, or build it from your packs' schema.json:
+            bin/rails event_engine:catalog
+        MSG
+      end
     end
   end
 end

data/lib/event_engine/rules_file.rb

@@ -0,0 +1,14 @@
+require "yaml"
+
+module EventEngine
+  class RulesFile
+    def self.sync(path:, event_names:)
+      existing = File.exist?(path.to_s) ? (YAML.safe_load_file(path.to_s) || {}) : {}
+      decided = existing["events"] || {}
+      events = event_names.to_h { |name| [ name.to_s, decided[name.to_s] ] }
+
+      File.write(path, YAML.dump(existing.merge("events" => events)))
+      path
+    end
+  end
+end

data/lib/event_engine/schema_catalog_builder.rb

@@ -0,0 +1,18 @@
+require "json"
+
+module EventEngine
+  class SchemaCatalogBuilder
+    def self.build(sources:, catalog_path:)
+      entries = sources.flat_map { |source| read(source) }
+
+      File.write(catalog_path, "#{JSON.pretty_generate(entries)}\n")
+    end
+
+    def self.read(source)
+      contents = File.read(source.to_s)
+      return [] if contents.strip.empty?
+
+      JSON.parse(contents)
+    end
+  end
+end

data/lib/event_engine/schema_registry.rb

@@ -1,53 +1,26 @@
 module EventEngine
-  # In-memory registry holding all event schemas by name and version.
-  # Loaded once at boot from the compiled schema file.
-  #
-  # @example Look up a schema
-  #   schema = registry.schema(:cow_fed)
-  #   schema.event_version #=> 2
-  #
-  # @example Look up a specific version
-  #   schema = registry.schema(:cow_fed, version: 1)
   class SchemaRegistry
-    # Raised when looking up an event name or version that doesn't exist.
     class UnknownEventError < StandardError; end
 
-    # Raised when the registry is accessed before loading or loaded twice.
     class RegistryFrozenError < StandardError; end
 
-    # @param event_schema [EventSchema] initial schema (empty by default)
     def initialize(event_schema = EventSchema.new)
       @event_schema = event_schema
       @loaded = false
     end
 
-    # Registers a schema into the underlying EventSchema store.
-    #
-    # @param schema [EventDefinition::Schema] the schema to register
     def register(schema)
       @event_schema.register(schema)
     end
 
-    # Returns all registered event names.
-    #
-    # @return [Array<Symbol>]
     def events
       @event_schema.events
     end
 
-    # Returns all version numbers for a given event.
-    #
-    # @param event_name [Symbol]
-    # @return [Array<Integer>] sorted version numbers
-    def versions_for(event_name)
-      @event_schema.versions_for(event_name)
+    def versions_for(event_name, domain: nil)
+      @event_schema.versions_for(event_name, domain: domain)
     end
 
-    # Populates the registry from a loaded EventSchema. Can only be called once.
-    #
-    # @param schema [EventSchema] the compiled schema
-    # @return [self]
-    # @raise [RegistryFrozenError] if already loaded
     def load_from_schema!(schema)
       raise RegistryFrozenError, "EventRegistry already loaded" if loaded?
       @event_schema = schema
@@ -56,30 +29,19 @@ module EventEngine
       self
     end
 
-    # Clears the registry, allowing it to be reloaded.
-    #
-    # @return [void]
     def reset!
       @event_schema = {}
       @loaded = false
     end
 
-    # Looks up a schema by event name and optional version.
-    # Returns the latest version when no version is specified.
-    #
-    # @param event_name [Symbol]
-    # @param version [Integer, nil] specific version, or nil for latest
-    # @return [EventDefinition::Schema]
-    # @raise [RegistryFrozenError] if registry is not loaded
-    # @raise [UnknownEventError] if event or version is not found
-    def schema(event_name, version: nil)
+    def schema(event_name, version: nil, domain: nil)
       raise RegistryFrozenError, "EventRegistry not loaded" unless loaded?
 
       schema =
         if version
-          @event_schema.schema_for(event_name, version)
+          @event_schema.schema_for(event_name, version, domain: domain)
         else
-          @event_schema.latest_for(event_name)
+          @event_schema.latest_for(event_name, domain: domain)
         end
 
       unless schema
@@ -90,31 +52,18 @@ module EventEngine
       schema
     end
 
-    # Returns the latest schema version for an event.
-    #
-    # @param event_name [Symbol]
-    # @return [EventDefinition::Schema, nil]
-    def latest_for(event_name)
-      @event_schema.latest_for(event_name)
+    def latest_for(event_name, domain: nil)
+      @event_schema.latest_for(event_name, domain: domain)
     end
 
-    # Returns the underlying EventSchema store.
-    #
-    # @return [EventSchema]
     def event_schema
       @event_schema
     end
 
-    # Freezes the underlying schema, preventing further modifications.
-    #
-    # @return [void]
     def finalize!
       @event_schema.finalize!
     end
 
-    # Whether the registry has been loaded with schemas.
-    #
-    # @return [Boolean]
     def loaded?
       @loaded == true
     end

data/lib/event_engine/unregistered_processor_error.rb

@@ -0,0 +1,8 @@
+module EventEngine
+  class UnregisteredProcessorError < StandardError
+    def initialize(name, event)
+      super("the rule for event #{event.event_name.inspect} (pack #{event.domain.inspect}) " \
+            "names processor #{name.inspect}, but no processor is registered under that name")
+    end
+  end
+end

data/lib/event_engine/unroutable_event_error.rb

@@ -0,0 +1,9 @@
+module EventEngine
+  class UnroutableEventError < StandardError
+    def initialize(event)
+      super("no processing rule for event #{event.event_name.inspect} " \
+            "(pack #{event.domain.inspect}); declare it in the rules file " \
+            "under events, packs, or default")
+    end
+  end
+end