event_engine-event_definition 0.2.0

data/lib/event_engine/event_definition/payloads.rb

@@ -0,0 +1,33 @@
+module EventEngine
+  class EventDefinition
+    module Payloads
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        def optional_payload(name, from: nil, attr: nil)
+          payload_fields << {
+            name: name.to_sym,
+            required: false,
+            from: from,
+            attr: attr
+          }
+        end
+
+        def required_payload(name, from: nil, attr: nil)
+          payload_fields << {
+            name: name.to_sym,
+            required: true,
+            from: from,
+            attr: attr
+          }
+        end
+
+        def payload_fields
+          @payload_fields ||= []
+        end
+      end
+    end
+  end
+end

data/lib/event_engine/event_definition/schemas.rb

@@ -0,0 +1,178 @@
+require "json"
+require "digest"
+
+module EventEngine
+  class EventDefinition
+    module Schemas
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      class Schema < 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
+
+        def to_ruby
+          <<~RUBY.strip
+            EventEngine::EventDefinition::Schema.new(
+              event_name: #{event_name.inspect},
+              event_version: #{event_version.inspect},
+              event_type: #{event_type.inspect},
+              subject: #{subject.inspect},
+              domain: #{domain.inspect},
+              required_inputs: #{required_inputs.inspect},
+              optional_inputs: #{optional_inputs.inspect},
+              payload_fields: [#{payload_fields.map { |h| ruby_hash(h) }.join(", ")}]
+            )
+          RUBY
+        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
+
+        def ruby_hash(hash)
+          inner = hash.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")
+          "{#{inner}}"
+        end
+      end
+
+      module ClassMethods
+        def schema
+          errors = schema_errors
+          raise ArgumentError, errors.join(", ") if errors.any?
+
+          required = inputs.select { |_, v| v== :required }.keys
+          optional = inputs.select { |_, v| v== :optional }.keys
+
+          Schema.new(
+            event_name: @event_name,
+            event_type: @event_type,
+            subject: @subject,
+            domain: @domain,
+            required_inputs: required,
+            optional_inputs: optional,
+            payload_fields: payload_fields
+          )
+        end
+
+        def schema_errors
+          errors = []
+          validate_identity(errors)
+          validate_payload_fields(errors)
+          errors
+        end
+
+        def valid_schema?
+          schema_errors.empty?
+        end
+
+        private
+
+        def validate_identity(errors)
+          errors << "event_name is required" unless @event_name
+          errors << "event_type is required" unless @event_type
+        end
+
+        def validate_payload_fields(errors)
+          seen = {}
+
+          payload_fields.each do |field|
+            name = field[:name]
+
+            if seen[name]
+              errors << "duplicate payload field: #{name}"
+            end
+
+            if RESERVED_PAYLOAD_FIELDS.include?(name)
+              errors << "payload field uses reserved name: #{name}"
+            end
+
+            if field[:from].nil?
+              errors << "payload field #{name} must have a from:"
+            end
+
+            unless inputs.key?(field[:from])
+              errors << "payload field #{name} references unknown input: #{field[:from]}"
+            end
+
+            seen[name] = true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/event_engine/event_definition/validation.rb

@@ -0,0 +1,18 @@
+module EventEngine
+  class EventDefinition
+    module Validation
+      def validate_inputs!(inputs)
+        declared = self.class.inputs
+        provided = inputs.keys.map(&:to_sym)
+
+        return if declared.empty?
+
+        missing = declared - provided
+        raise ArgumentError, "missing input: #{missing.join(', ')}" if missing.any?
+
+        extra = provided - declared
+        raise ArgumentError, "undeclared input: #{extra.join(', ')}" if extra.any?
+      end
+    end
+  end
+end

data/lib/event_engine/event_definition.rb

@@ -0,0 +1,48 @@
+require "event_engine/event_definition/inputs"
+require "event_engine/event_definition/payloads"
+require "event_engine/event_definition/validation"
+require "event_engine/event_definition/schemas"
+
+module EventEngine
+  class EventDefinition
+    RESERVED_PAYLOAD_FIELDS = %i[
+      event_name
+      event_type
+      event_version
+      occurred_at
+      created_at
+      updated_at
+      published_at
+      metadata
+      idempotency_key
+      attempts
+      dead_lettered_at
+      aggregate_type
+      aggregate_id
+      aggregate_version
+    ].freeze
+
+    include Inputs
+    include Payloads
+    include Validation
+    include Schemas
+
+    class << self
+      def event_name(value)
+        @event_name = value
+      end
+
+      def event_type(value)
+        @event_type = value
+      end
+
+      def subject(value)
+        @subject = value
+      end
+
+      def domain(value)
+        @domain = value
+      end
+    end
+  end
+end

data/lib/event_engine/event_engine_helpers_writer.rb

@@ -0,0 +1,100 @@
+module EventEngine
+  class EventEngineHelpersWriter
+    HEADER = <<~RUBY.freeze
+      # This file is authoritative in production.
+      # It is generated from EventDefinitions via:
+      #
+      #   bin/rails event_engine:schema:dump
+      #
+      # Do not edit manually.
+
+    RUBY
+
+    ENVELOPE_KEYS = DslCompiler::RESERVED_INPUT_NAMES
+
+    def self.write(path, event_schema, root_module: "EventEngine", emit: "EventEngine.emit",
+                   header: HEADER, group_by_domain: true, schema_filename: nil)
+      File.write(
+        path,
+        generate(event_schema, root_module: root_module, emit: emit, header: header,
+                               group_by_domain: group_by_domain, schema_filename: schema_filename)
+      )
+    end
+
+    def self.generate(event_schema, root_module: "EventEngine", emit: "EventEngine.emit",
+                      header: HEADER, group_by_domain: true, schema_filename: nil)
+      body = group_by_domain ? grouped_body(event_schema, emit) : flat_body(event_schema, emit)
+      body = "#{schema_path_accessor(schema_filename)}#{body}" if schema_filename
+
+      "#{header}module #{root_module}\n#{body}end\n"
+    end
+
+    def self.schema_path_accessor(filename)
+      "  def self.schema_path\n    File.expand_path(#{filename.inspect}, __dir__)\n  end\n"
+    end
+
+    def self.grouped_body(event_schema, emit)
+      events_by_domain(event_schema).map do |domain, event_names|
+        helpers = helpers_for(event_schema, domain, event_names, emit, indent: 4)
+
+        "  module #{module_name(domain)}\n#{helpers}  end\n"
+      end.join
+    end
+
+    def self.flat_body(event_schema, emit)
+      events_by_domain(event_schema).map do |domain, event_names|
+        helpers_for(event_schema, domain, event_names, emit, indent: 2)
+      end.join
+    end
+
+    def self.helpers_for(event_schema, domain, event_names, emit, indent:)
+      event_names.map do |event_name|
+        helper(domain, event_schema.latest_for(event_name, domain: domain), emit, indent)
+      end.join
+    end
+
+    def self.events_by_domain(event_schema)
+      event_schema.schemas_by_event.keys
+        .group_by { |(domain, _event_name)| domain }
+        .transform_values { |pairs| pairs.map { |(_domain, event_name)| event_name }.sort }
+    end
+
+    def self.module_name(domain)
+      domain.to_s.split("_").map(&:capitalize).join
+    end
+
+    def self.helper(domain, schema, emit, indent)
+      pad = " " * indent
+      call_pad = " " * (indent + 2)
+      arg_pad = " " * (indent + 4)
+
+      arguments = [
+        schema.event_name.inspect,
+        "domain: #{domain.inspect}",
+        "inputs: #{inputs_hash(schema)}",
+        *ENVELOPE_KEYS.map { |name| "#{name}: #{name}" }
+      ].map { |argument| "#{arg_pad}#{argument}" }.join(",\n")
+
+      "#{pad}def self.#{schema.event_name}(#{signature(schema)})\n" \
+        "#{call_pad}#{emit}(\n" \
+        "#{arguments}\n" \
+        "#{call_pad})\n" \
+        "#{pad}end\n"
+    end
+
+    def self.signature(schema)
+      required = schema.required_inputs.map { |name| "#{name}:" }
+      optional = schema.optional_inputs.map { |name| "#{name}: nil" }
+      envelope = ENVELOPE_KEYS.map { |name| "#{name}: nil" }
+
+      (required + optional + envelope).join(", ")
+    end
+
+    def self.inputs_hash(schema)
+      inputs = schema.required_inputs + schema.optional_inputs
+      return "{}" if inputs.empty?
+
+      "{ #{inputs.map { |name| "#{name}: #{name}" }.join(", ")} }"
+    end
+  end
+end

data/lib/event_engine/event_schema.rb

@@ -0,0 +1,80 @@
+module EventEngine
+  class EventSchema
+    class DuplicateEventNameError < StandardError; end
+
+    def self.define(&block)
+      schema = new
+      block.call(schema)
+      schema
+    end
+
+    def initialize
+      @schemas_by_event = {}
+      @finalized = false
+    end
+
+    def register(schema)
+      raise FrozenError, "EventSchema is finalized" if @finalized
+      key = key_for(schema.domain, schema.event_name)
+      version = schema.event_version
+
+      @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 (domain, event_name) " \
+            "(#{incoming.domain.inspect}, #{incoming.event_name.inspect}): " \
+            "already registered at version #{existing.event_version.inspect}"
+    end
+
+    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
+
+    def versions_for(event_name, domain: nil)
+      version_sets_for(event_name, domain).flat_map(&:keys).uniq.sort
+    end
+
+    def schema_for(event_name, version, domain: nil)
+      set = version_sets_for(event_name, domain).find { |versions| versions.key?(version) }
+      set && set[version]
+    end
+
+    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
+
+    def finalize!
+      @finalized = true
+      @schemas_by_event.each_value(&:freeze)
+      @schemas_by_event.freeze
+      freeze
+    end
+
+    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/lifecycle_definition.rb

@@ -0,0 +1,77 @@
+require "event_engine/event_definition"
+
+module EventEngine
+  class LifecycleDefinition
+    include EventDefinition::Inputs
+    include EventDefinition::Payloads
+
+    class << self
+      def subject(value)
+        @subject = value
+      end
+
+      def event_type(value)
+        @event_type = value
+      end
+
+      def lifecycle(*verbs)
+        @verbs = verbs
+      end
+
+      def on(verb, &block)
+        verb_overrides[verb] = block
+      end
+
+      def verb_overrides
+        @verb_overrides ||= {}
+      end
+
+      def generated_events
+        @generated_events ||= Array(@verbs).map { |verb| build_event(verb) }
+      end
+
+      def materialize_all!
+        subclasses.flat_map(&:generated_events)
+      end
+
+      def declared_subject
+        @subject
+      end
+
+      def declared_event_type
+        @event_type
+      end
+
+      private
+
+      def build_event(verb)
+        template = self
+        name = :"#{template.declared_subject}_#{verb}"
+
+        Class.new(EventDefinition) do
+          event_name name
+          event_type template.declared_event_type
+
+          define_singleton_method(:inspect) { "EventEngine::LifecycleDefinition(#{name})" }
+          define_singleton_method(:to_s) { inspect }
+          subject template.declared_subject
+
+          template.inputs.each do |name, kind|
+            kind == :required ? input(name) : optional_input(name)
+          end
+
+          template.payload_fields.each do |field|
+            if field[:required]
+              required_payload field[:name], from: field[:from], attr: field[:attr]
+            else
+              optional_payload field[:name], from: field[:from], attr: field[:attr]
+            end
+          end
+
+          override = template.verb_overrides[verb]
+          class_eval(&override) if override
+        end
+      end
+    end
+  end
+end

data/lib/event_engine/schema_registry.rb

@@ -0,0 +1,71 @@
+module EventEngine
+  class SchemaRegistry
+    class UnknownEventError < StandardError; end
+
+    class RegistryFrozenError < StandardError; end
+
+    def initialize(event_schema = EventSchema.new)
+      @event_schema = event_schema
+      @loaded = false
+    end
+
+    def register(schema)
+      @event_schema.register(schema)
+    end
+
+    def events
+      @event_schema.events
+    end
+
+    def versions_for(event_name, domain: nil)
+      @event_schema.versions_for(event_name, domain: domain)
+    end
+
+    def load_from_schema!(schema)
+      raise RegistryFrozenError, "EventRegistry already loaded" if loaded?
+      @event_schema = schema
+
+      @loaded = true
+      self
+    end
+
+    def reset!
+      @event_schema = {}
+      @loaded = false
+    end
+
+    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, domain: domain)
+        else
+          @event_schema.latest_for(event_name, domain: domain)
+        end
+
+      unless schema
+        raise UnknownEventError,
+              "Unknown #{version ? "version #{version} for " : ""}event: #{event_name}"
+      end
+
+      schema
+    end
+
+    def latest_for(event_name, domain: nil)
+      @event_schema.latest_for(event_name, domain: domain)
+    end
+
+    def event_schema
+      @event_schema
+    end
+
+    def finalize!
+      @event_schema.finalize!
+    end
+
+    def loaded?
+      @loaded == true
+    end
+  end
+end

data/lib/event_engine/subject_registry.rb

@@ -0,0 +1,40 @@
+module EventEngine
+  class SubjectRegistry
+    class UnknownSubjectError < StandardError; end
+
+    class Subject
+      attr_reader :name, :metadata
+
+      def initialize(name, **metadata)
+        @name = name
+        @metadata = metadata
+      end
+    end
+
+    def self.define(&block)
+      registry = new
+      registry.instance_eval(&block) if block
+      registry
+    end
+
+    def initialize
+      @subjects = {}
+    end
+
+    def subject(name, **metadata)
+      @subjects[name] = Subject.new(name, **metadata)
+    end
+
+    def [](name)
+      @subjects[name]
+    end
+
+    def registered?(name)
+      @subjects.key?(name)
+    end
+
+    def names
+      @subjects.keys
+    end
+  end
+end

data/lib/tasks/event_engine_definition.rake

@@ -0,0 +1,19 @@
+require "event_engine/definition"
+
+namespace :event_engine do
+  namespace :definition do
+    desc "Generate the pack's helper and schema.json from its EventDefinitions"
+    task :dump do
+      config = EventEngine::Definition.configuration
+
+      definitions = EventEngine::DefinitionLoader.load!(config.definitions_path)
+
+      EventEngine::DomainPackBuild.run(
+        definitions,
+        helper_path: config.helper_path,
+        root_module: config.root_module,
+        subject_registry: config.subject_registry
+      )
+    end
+  end
+end

data/sig/event_engine/definition.rbs

@@ -0,0 +1,6 @@
+module EventEngine
+  module Definition
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end