event_engine 0.1.0 → 0.2.0

data/lib/event_engine/unrouted_events_error.rb

@@ -0,0 +1,9 @@
+module EventEngine
+  class UnroutedEventsError < StandardError
+    def initialize(event_names)
+      super("no processing rule routes #{event_names.map(&:inspect).join(", ")}; " \
+            "declare #{event_names.one? ? "it" : "them"} in the rules file " \
+            "under events, packs, or default")
+    end
+  end
+end

data/lib/event_engine/version.rb

@@ -1,3 +1,3 @@
 module EventEngine
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/event_engine.rb

@@ -1,56 +1,31 @@
 require_relative "event_engine/version"
 
-require "event_engine/engine"
+require "event_engine/railtie"
 require "event_engine/configuration"
-require "event_engine/process_type"
-require "event_engine/event_definition"
-require "event_engine/lifecycle_definition"
+require "event_engine/catalog_entry"
 require "event_engine/event_builder"
+require "event_engine/definition_publisher"
 require "event_engine/handler_registry"
+require "event_engine/processor_registry"
+require "event_engine/unroutable_event_error"
+require "event_engine/unregistered_processor_error"
+require "event_engine/invalid_rules_error"
+require "event_engine/unrouted_events_error"
+require "event_engine/processor_resolver"
+require "event_engine/processing_rules"
+require "event_engine/rules_file"
 require "event_engine/event_schema"
 require "event_engine/schema_registry"
-require "event_engine/subject_registry"
 require "event_engine/event"
-require "event_engine/dsl_compiler"
-require "event_engine/event_schema_loader"
-require "event_engine/event_schema_writer"
-require "event_engine/event_schema_merger"
-require "event_engine/event_schema_dumper"
-require "event_engine/schema_drift_guard"
-require "event_engine/schema_compatibility"
-require "event_engine/schema_catalog"
-require "event_engine/railtie"
-require "event_engine/definition_loader"
-require "event_engine/the_local"
-
-# EventEngine is the schema-first core of the event pipeline.
-#
-# Events are defined via a Ruby DSL and compiled into a canonical schema file.
-# At boot, a helper method is installed on this module for each registered event
-# (e.g. +EventEngine.cow_fed(cow: cow)+); the helper validates inputs, builds an
-# +Event+, and dispatches it to registered handlers by level. Companion gems
-# (e.g. event_engine-delivery) register handlers to process the events.
-#
-# @example Define, build, and dispatch an event
-#   EventEngine.register_handler(MyHandler, levels: :all)
-#   EventEngine.cow_fed(cow: cow, occurred_at: Time.current)
+require "event_engine/event_schema_json_loader"
+require "event_engine/schema_catalog_builder"
+
 module EventEngine
-  mattr_accessor :_installed_event_helpers, default: Set.new
   class << self
-    # Returns the current configuration instance.
-    #
-    # @return [Configuration]
     def configuration
       @configuration ||= Configuration.new
     end
 
-    # Yields the configuration for modification.
-    #
-    # @yieldparam config [Configuration] the configuration instance
-    # @example
-    #   EventEngine.configure do |config|
-    #     config.logger = Rails.logger
-    #   end
     def configure
       yield(configuration)
     end
@@ -59,16 +34,81 @@ module EventEngine
       @handler_registry ||= HandlerRegistry.new
     end
 
-    def subject_registry
-      @subject_registry ||= SubjectRegistry.new
+    def processor_registry
+      @processor_registry ||= ProcessorRegistry.new
+    end
+
+    def schema_registry
+      @schema_registry ||= SchemaRegistry.new
+    end
+
+    attr_writer :schema_registry
+
+    def emit(event_name, inputs:, domain: nil, event_version: nil, occurred_at: nil,
+             metadata: nil, idempotency_key: nil, aggregate_type: nil,
+             aggregate_id: nil, aggregate_version: nil)
+      schema = schema_registry.schema(event_name, version: event_version, domain: domain)
+
+      attrs = EventBuilder.build(schema: schema, data: inputs)
+      attrs[:occurred_at] = occurred_at || Time.current
+      attrs[:metadata] = enriched_metadata(metadata)
+      attrs[:idempotency_key] = idempotency_key || SecureRandom.uuid
+      attrs[:aggregate_type] = aggregate_type
+      attrs[:aggregate_id] = aggregate_id
+      attrs[:aggregate_version] = aggregate_version
+      attrs[:process_type] = processing_rules.for(event_name: schema.event_name, pack: schema.domain)
+      attrs[:subject] = schema.subject
+      attrs[:domain] = schema.domain
+
+      event = Event.new(**attrs)
+      process(event)
+      dispatch(event)
+    end
+
+    def processing_rules
+      @processing_rules ||= ProcessingRules.load(configuration.rules_path)
+    end
+
+    attr_writer :processing_rules
+
+    def validate_rules!
+      missing = processing_rules.processor_names.reject { |name| processor_registry.fetch(name) }
+      raise InvalidRulesError, missing if missing.any?
+
+      raise UnroutedEventsError, unrouted_events if unrouted_events.any?
+
+      true
+    end
+
+    def unrouted_events
+      return [] unless processing_rules.any?
+
+      schema_registry.events.reject do |event_name|
+        processing_rules.for(event_name: event_name, pack: schema_registry.latest_for(event_name).domain)
+      end
+    end
+
+    def schema_sources(port = definition_port)
+      configured = configuration.publisher_schema_paths
+      return configured if configured.any?
+
+      discovered_schema_paths(port)
+    end
+
+    def discovered_schema_paths(port = definition_port)
+      return [] unless port.respond_to?(:pack_schema_paths)
+
+      port.pack_schema_paths
     end
 
-    def define_subjects(&block)
-      subject_registry.instance_eval(&block)
+    def register_definition_publisher!(port = definition_port)
+      return nil unless port.respond_to?(:publisher=)
+
+      port.publisher = DefinitionPublisher.new
     end
 
-    def reset_subjects!
-      @subject_registry = nil
+    def definition_port
+      ::EventEngine::Definition if defined?(::EventEngine::Definition)
     end
 
     def enriched_metadata(call_site_metadata)
@@ -88,107 +128,61 @@ module EventEngine
       nil
     end
 
-    def register_handler(handler, levels:)
-      handler_registry.register(handler, levels: levels)
+    def register_handler(handler, process_types:)
+      handler_registry.register(handler, process_types: process_types)
+    end
+
+    def register_processor(name, processor)
+      processor_registry.register(name, processor)
     end
 
     def dispatch(event)
       handler_registry.dispatch(event)
     end
 
+    def process(event)
+      resolver = ProcessorResolver.new(processing_rules)
+      return event unless resolver.routes?
+
+      name = resolver.resolve(event)
+      processor = processor_registry.fetch(name) || raise(UnregisteredProcessorError.new(name, event))
+
+      processor.call(event)
+      event
+    end
+
     def reset_handlers!
       handler_registry.clear!
     end
 
-    # Loads a schema file, populates the registry, and installs helper methods.
-    # Called automatically by the engine at Rails boot.
-    #
-    # @param schema_path [String, Pathname] path to the compiled schema file
-    # @param registry [SchemaRegistry] the registry to populate
-    # @return [EventSchema] the loaded schema
+    def reset_processors!
+      processor_registry.clear!
+    end
+
     def boot_from_schema!(schema_path:, registry:)
-      event_schema = EventSchemaLoader.load(schema_path)
+      event_schema = EventSchemaJsonLoader.load(schema_path)
 
       registry.reset!
       registry.load_from_schema!(event_schema)
 
-      install_helpers(registry: registry)
+      self.schema_registry = registry
 
       event_schema
     end
 
-    # Installs singleton helper methods on the EventEngine module for each
-    # event in the registry. Previous helpers are removed first.
-    #
-    # @param registry [SchemaRegistry] the loaded registry
-    def install_helpers(registry:)
-      _installed_event_helpers.each do |method_name|
-        singleton_class.remove_method(method_name) if singleton_class.method_defined?(method_name)
-      end
-      _installed_event_helpers.clear
-
-      registry.events.each do |event_name|
-        schema = registry.schema(event_name)
-
-        required = schema.required_inputs
-        optional = schema.optional_inputs
-
-        define_singleton_method(event_name) do |**args|
-          event_version = args.delete(:event_version)
-          occurred_at = args.delete(:occurred_at)
-          metadata = args.delete(:metadata)
-          idempotency_key = args.delete(:idempotency_key)
-          aggregate_type = args.delete(:aggregate_type)
-          aggregate_id = args.delete(:aggregate_id)
-          aggregate_version = args.delete(:aggregate_version)
-
-          input_keys = required + optional
-          inputs = args.slice(*input_keys)
-
-          missing = required - inputs.keys
-          raise ArgumentError, "Missing required inputs: #{missing.join(', ')}" if missing.any?
-
-          unknown = args.keys - input_keys
-          raise ArgumentError, "Unknown inputs: #{unknown.join(', ')}" if unknown.any?
-
-          schema = registry.schema(event_name, version: event_version)
-          attrs = EventBuilder.build(schema: schema, data: inputs)
-          attrs[:occurred_at] = occurred_at || Time.current
-          attrs[:metadata] = EventEngine.enriched_metadata(metadata)
-          attrs[:idempotency_key] = idempotency_key || SecureRandom.uuid
-          attrs[:aggregate_type] = aggregate_type
-          attrs[:aggregate_id] = aggregate_id
-          attrs[:aggregate_version] = aggregate_version
-          attrs[:process_type] = schema.process_type
-          attrs[:subject] = schema.subject
-          attrs[:domain] = schema.domain
-
-          EventEngine.dispatch(Event.new(**attrs))
-        end
-
-        _installed_event_helpers << event_name
+    def register_slice!(schema_path:)
+      slice = EventSchemaJsonLoader.load(schema_path)
+
+      schema_registry.load_from_schema!(EventSchema.new) unless schema_registry.loaded?
+      slice.event_schema.schemas_by_event.each_value do |versions|
+        versions.each_value { |schema| schema_registry.register(schema) }
       end
-    end
 
-    # Compiles event definitions from source into a registry.
-    # Used by rake tasks for schema drift detection.
-    #
-    # @return [SchemaRegistry]
-    def compiled_schema_registry
-      DefinitionLoader.ensure_loaded!
-      definitions = EventDefinition.descendants
-      compiled = DslCompiler.compile(definitions)
-      registry = SchemaRegistry.new
-      registry.load_from_schema!(compiled)
-      registry
+      schema_registry
     end
 
-    # Loads the committed schema file into a registry.
-    # Used by rake tasks for schema drift detection.
-    #
-    # @return [SchemaRegistry]
-    def file_schema_registry
-      loaded = EventSchemaLoader.load(Rails.root.join("db/event_schema.rb"))
+    def file_schema_registry(schema_path: configuration.schema_path)
+      loaded = EventSchemaJsonLoader.load(schema_path)
       registry = SchemaRegistry.new
       registry.load_from_schema!(loaded)
       registry

data/lib/tasks/event_engine_catalog.rake

@@ -1,13 +1,22 @@
 namespace :event_engine do
-  desc "Render the event schema and subjects as a markdown catalog"
+  desc "Build the committed catalog from every pack, and keep the rules file in step"
   task catalog: :environment do
-    EventEngine::DefinitionLoader.ensure_loaded!
+    catalog_path = Rails.root.join(EventEngine.configuration.schema_path)
 
-    catalog = EventEngine::SchemaCatalog.new(
-      schema_registry: EventEngine.file_schema_registry,
-      subject_registry: EventEngine.subject_registry
+    EventEngine::SchemaCatalogBuilder.build(
+      sources: EventEngine.schema_sources,
+      catalog_path: catalog_path
     )
 
-    puts catalog.to_markdown
+    puts "Wrote EventEngine catalog to #{catalog_path}"
+
+    rules_path = Rails.root.join(EventEngine.configuration.rules_path)
+
+    EventEngine::RulesFile.sync(
+      path: rules_path,
+      event_names: JSON.parse(File.read(catalog_path)).map { |entry| entry["event_name"] }
+    )
+
+    puts "Wrote EventEngine processing rules to #{rules_path}"
   end
 end

data/lib/tasks/event_engine_rules.rake

@@ -0,0 +1,10 @@
+namespace :event_engine do
+  namespace :rules do
+    desc "Check that every processing rule names a registered processor"
+    task check: :environment do
+      EventEngine.validate_rules!
+
+      puts "EventEngine rules OK: #{EventEngine.processing_rules.processor_names.map(&:inspect).join(", ")}"
+    end
+  end
+end

data/the_local/agents/event_engine-develop.md

@@ -0,0 +1,154 @@
+---
+name: event_engine-develop
+description: Use PROACTIVELY for wiring an app's event processing on event_engine — registering processors and handlers, routing events to the right processor, building the committed schema catalog from event packs, and printing the catalog — MUST BE USED instead of hand-rolling event dispatch, a processor lookup table, or a script that stitches pack schemas together.
+tools: Read, Write, Edit, Grep
+scope: events — registering processors and publishers, building the schema catalog, and directing emitted events to the right processor
+---
+
+This local wires a host app's event processing on event_engine, following the
+steps below in order. Where a step names a decision, it asks the developer
+instead of choosing.
+
+## What event_engine is
+
+A Rails engine that loads a committed catalog of event schemas at boot, turns an
+event pack's raw inputs into a checked event, sends that event to exactly one
+**processor**, and then to every matching **handler**. Fire this local when an app
+needs its events built, routed, or catalogued — anything from "our pack's events
+aren't reaching the subscriber" to "add the new pack's schema to the app".
+
+## Interface
+
+- `publisher_schema_paths` — configuration setting; the list of pack `schema.json`
+  files the catalog is built from. Defaults to empty.
+- `bin/rails event_engine:schema:catalog` — reads every `publisher_schema_paths`
+  source and writes them into the app's committed catalog at `db/event_schema.json`.
+- `EventEngine.register_processor` — registers a processor under a name, so a
+  routing setting can point at that name.
+- `event_processors` — configuration setting; a hash of event name → processor
+  name. The most specific routing rule.
+- `domain_processors` — configuration setting; a hash of domain → processor name.
+  Applies to every event in that domain.
+- `default_processor` — configuration setting; the processor name used when no
+  event or domain rule matches.
+- `EventEngine.register_handler` — registers a handler that runs after the
+  processor, filtered by the event's process type.
+- `EventEngine.register_definition_publisher!` — points a pack's publisher port at
+  event_engine, so the pack's helpers produce real events. Runs automatically at
+  boot; call it directly only for a port other than the default.
+- `bin/rails event_engine:catalog` — prints the catalogued events as markdown.
+
+## How to use it
+
+All configuration below goes in the host app's
+`config/initializers/event_engine.rb`, on the configuration object yielded inside
+it. The `event_engine-install` local creates that file — if it is missing, hand
+off to that local first and come back.
+
+1. Set `publisher_schema_paths` to the `schema.json` of every pack whose events
+   this app handles. Ask the developer which packs are in scope; do not infer the
+   list from the Gemfile, and do not guess a path.
+
+   ```ruby
+   config.publisher_schema_paths = [
+     MarketingEvents.schema_path,
+     SalesEvents.schema_path
+   ]
+   ```
+
+   Leave this unset and step 2 writes an empty catalog — no event is emittable.
+
+2. Build the catalog and commit it:
+
+   ```bash
+   bin/rails event_engine:schema:catalog
+   ```
+
+   It writes `db/event_schema.json` from the sources, in order, overwriting the
+   file. It never edits a source, and it never recomputes a schema's fingerprint —
+   what a pack published is what lands. Commit the result; the app reads that file
+   at boot, warns in `development` and `test` when it is absent, and refuses to
+   boot in every other environment. Re-run it whenever a pack's schema changes or
+   a pack is added to step 1.
+
+3. Register each processor by name, in the initializer, so the names exist before
+   any event is emitted. A processor is anything responding to `#call(event)`:
+
+   ```ruby
+   EventEngine.register_processor(:subscribers, MyApp::SubscriberProcessor)
+   ```
+
+   Registering the same name twice replaces the earlier one.
+
+4. Route events to those processors with the three settings. Ask the developer how
+   their events should route — there is no safe default, and the right answer
+   depends on which processors the app actually runs:
+
+   ```ruby
+   config.default_processor = :subscribers
+   config.domain_processors = { marketing: :delivery }
+   config.event_processors  = { lead_created: :telemetry }
+   ```
+
+   Resolution is `event_processors[event_name]`, then
+   `domain_processors[domain]`, then `default_processor` — first match wins.
+   Every name used here must be registered in step 3.
+
+5. Register handlers. A handler is anything responding to `#call(event)`, and it
+   runs after the processor. `process_types:` is required — either `:all`, or a
+   list of process types that is matched against the event's own process type:
+
+   ```ruby
+   EventEngine.register_handler(MyApp::AuditLog, process_types: %i[durable broker])
+   EventEngine.register_handler(MyApp::Firehose, process_types: :all)
+   ```
+
+   Every handler whose filter matches runs, in registration order. An event with
+   no matching handler is still built and processed.
+
+6. Leave the publisher port alone unless the app has one of its own. At boot the
+   engine points the default port at event_engine, which is what makes a pack's
+   generated helper produce a real event instead of raising. Call it directly only
+   to install it on a different port object:
+
+   ```ruby
+   EventEngine.register_definition_publisher!(MyApp::CustomPort)
+   ```
+
+   It is a no-op returning `nil` when the port cannot accept a publisher — which
+   is also what happens when no pack is loaded.
+
+7. Verify the wiring:
+
+   ```bash
+   bin/rails event_engine:catalog
+   ```
+
+   It prints one markdown section per catalogued event — name, version, type,
+   subject, payload fields — read from the committed catalog. An event missing
+   here will not emit; go back to step 1.
+
+## Conventions
+
+- Both processors and handlers receive the same built event, carrying
+  `event_name`, `event_type`, `event_version`, `process_type`, `subject`,
+  `domain`, `payload`, `metadata`, `occurred_at`, `idempotency_key`, and the
+  `aggregate_type` / `aggregate_id` / `aggregate_version` trio. Read from it; do
+  not mutate it.
+- The process types a handler filter can name are `inline`, `background`,
+  `durable`, `broker`, `telemetry`, and `sourced`. A schema declares one; the
+  filter is matched literally, so a typo silently never fires.
+- With none of the three routing settings set, no processor runs at all — events
+  are built and go straight to handlers. Once **any** of them is set, an event
+  matching none of the rules raises `EventEngine::UnroutableEventError` at emit.
+  Setting only `domain_processors` for one domain therefore breaks every other
+  domain; pair narrow rules with a `default_processor`.
+- Routing at a name with no registered processor fails at emit time, not at boot.
+  Keep steps 3 and 4 in the same initializer so they cannot drift.
+- A pack helper firing an event that is not in the committed catalog raises
+  `EventEngine::DefinitionPublisher::EventNotInCatalogError`. That means the
+  catalog is stale — rebuild it in step 2, do not work around it in app code.
+- Initializer changes need an app restart; nothing is re-read at runtime.
+- Out of scope for this local: adding the gem and writing the initializer itself
+  (`event_engine-install`), and authoring event definitions or packs — this local
+  consumes a pack's published `schema.json`, it never writes one.

data/the_local/agents/event_engine-info.md

@@ -0,0 +1,82 @@
+---
+name: event_engine-info
+description: Use to learn what event_engine offers — events, domains and subjects, process types, processors and handlers, and the schema catalog the rest of the gem reads from.
+tools: Read
+scope: events — registering processors and publishers, building the schema catalog, and directing emitted events to the right processor
+---
+
+This local explains event_engine and the vocabulary its world is built on. It
+changes nothing and gives no steps — read it to orient, then go to the local that
+owns the work.
+
+## What event_engine is
+
+event_engine is a Rails engine for applications that want events as a first-class
+seam rather than a pile of callbacks. Each event is described by a schema — a
+name, a version, the domain it belongs to, its subject, and the shape of its
+payload. Those schemas are aggregated into one committed catalog that the app
+loads at boot, and the catalog is authoritative: an event the catalog doesn't
+know cannot be emitted. Emitting is therefore a checked operation, and the set of
+events a system can produce is reviewable in a single file.
+
+Reach for it when several parts of an app need to react to the same domain
+occurrence, when you want the contract for those occurrences written down and
+diffable, or when different classes of event need to travel different roads —
+some handled in the request, some queued, some pushed to a broker, some recorded
+for telemetry or sourcing. An emitted event is checked against the catalog,
+routed to exactly one processor for that road, and then dispatched to any
+handlers subscribed to its process type. Routing is opt-in: configure nothing and
+events skip processing and go straight to handlers; configure any routing at all
+and an event with no matching processor is an error rather than a silent drop.
+
+## Interface
+
+This local documents no commands — it is background only.
+
+The `event_engine-install` local owns hooking the engine into a host app and
+configuring it. The `event_engine-develop` local owns the working surface:
+registering processors, publishers and handlers, pointing the engine at the
+schema sources it should aggregate, choosing how events route, and the rake tasks
+that build and render the catalog. Everything you would actually call or run
+lives in one of those two.
+
+## How to use it
+
+One decision: are you wiring event_engine into an app for the first time, or
+building with it?
+
+- Standing the engine up in a host app, or changing how it is configured →
+  `event_engine-install`.
+- Adding events, registering processors or handlers, setting up routing,
+  publishing a pack's schema, or rebuilding the catalog → `event_engine-develop`.
+
+If you only needed the vocabulary, you have it — stop here.
+
+## Conventions
+
+- **Event** — one occurrence, identified by an `event_name` and an
+  `event_version`. Carries a payload plus an envelope: metadata, the time it
+  occurred, an idempotency key, and optional aggregate identity
+  (`aggregate_type`, `aggregate_id`, `aggregate_version`).
+- **Domain** — the bounded area an event belongs to. Event names are looked up
+  within a domain, so the same name may exist in more than one.
+- **Subject** — the thing an event is about, declared in its own registry with
+  metadata. Subjects are named vocabulary shared across events, not per-event
+  fields.
+- **Process type** — how an event should travel: `inline`, `background`,
+  `durable`, `broker`, `telemetry`, or `sourced`. It comes from the schema, not
+  the call site.
+- **Processor** — the single destination an event is routed to. Resolution is
+  most-specific-first: a processor bound to the event name, then one bound to the
+  domain, then the configured default.
+- **Handler** — a subscriber that runs after processing. Handlers are registered
+  against process types (or all of them), and every match runs. Many handlers per
+  event; one processor.
+- **Catalog** — the committed JSON file the app boots from, aggregated from each
+  publishing pack's own `schema.json`. Packs own their schemas; the catalog is
+  the assembled whole. If it is missing, development and test warn, other
+  environments refuse to boot.
+- **Publisher** — the seam a pack emits through, so a pack depends on a small
+  publishing port rather than on the engine's internals.
+- **Version** — omit one when emitting and the latest schema for that event wins;
+  name one to pin.