event_rail 0.1.0

data/lib/event_rail/internal/identity.rb

@@ -0,0 +1,90 @@
+require "active_support/core_ext/digest/uuid"
+require "bigdecimal"
+require "date"
+
+module EventRail
+  module Internal
+    # Retry-stable publication identity.
+    #
+    # The whole point is that the same logical fact, published again by the same
+    # execution, derives the same event ID -- so a consumer can collapse the
+    # duplicates at-least-once delivery guarantees it will see. That makes both the
+    # namespace and the encoding permanent compatibility state: changing either
+    # silently gives every future publication a different ID for an unchanged fact,
+    # which is why the golden vectors are asserted rather than merely computed.
+    module Identity
+      module_function
+
+      # Derived from the URL namespace rather than written as a literal, so the input
+      # that produced it stays visible and a typo cannot masquerade as a deliberate
+      # value. The golden-vector test pins the result.
+      NAMESPACE = Digest::UUID.uuid_v5(
+        Digest::UUID::URL_NAMESPACE, "https://github.com/event_rail/event_rail/identity/v1"
+      ).freeze
+
+      # The first publication of an event type in one execution needs no key: there is
+      # nothing to distinguish it from.
+      SINGLETON = :__event_rail_singleton__
+
+      def derive(source:, job_class:, scope:, event_type:, version:, logical_identity:)
+        Digest::UUID.uuid_v5(
+          NAMESPACE,
+          encode([ source, job_class, scope, event_type, version, logical_identity ])
+        )
+      end
+
+      # Length-delimited and type-tagged. Ruby's own Hash#hash is per-process, inspect
+      # is not a format, and a plain join makes ["ab", "c"] and ["a", "bc"] the same
+      # string. A tag also keeps 1 and "1" apart, so a call site that passes an integer
+      # key cannot collide with one that passes its decimal spelling.
+      def encode(components)
+        components.map { |component| encode_component(component) }.join
+      end
+
+      def encode_component(value)
+        tag, bytes = case value
+        when SINGLETON then [ "*", "" ]
+        when String then [ "s", value.b ]
+        when true then [ "b", "true" ]
+        when false then [ "b", "false" ]
+        when Integer then [ "i", value.to_s ]
+        when BigDecimal
+          reject!(value, "a finite number") unless value.finite?
+          [ "d", value.to_s("F") ]
+        when Float
+          reject!(value, "a finite number") unless value.finite?
+          [ "f", format("%.17g", value) ]
+        when Time then [ "T", Timestamp.written(value) ]
+        when DateTime
+          reject!(value, "a Time rather than a DateTime")
+        when Date then [ "D", value.iso8601 ]
+        when Array
+          [ "L", "#{value.length}:#{encode(value.map { |item| encode_scalar!(item) })}" ]
+        else
+          reject!(value, "a non-null scalar")
+        end
+
+        "#{tag}#{bytes.bytesize}:#{bytes}"
+      end
+
+      # An identity component that is a structure cannot be canonicalized without
+      # choosing an ordering and a separator that would then be permanent, and one
+      # that is null cannot identify anything.
+      def encode_scalar!(value)
+        case value
+        when String, Integer, Float, BigDecimal, Time, true, false then value
+        when DateTime then reject!(value, "a Time rather than a DateTime")
+        when Date then value
+        else reject!(value, "a non-null scalar")
+        end
+      end
+      private_class_method :encode_scalar!
+
+      def reject!(value, expectation)
+        raise PublicationError,
+          "cannot derive publication identity from #{value.inspect}; every component must be #{expectation}"
+      end
+      private_class_method :reject!
+    end
+  end
+end

data/lib/event_rail/internal/notifications.rb

@@ -0,0 +1,42 @@
+require "active_support/notifications"
+
+module EventRail
+  module Internal
+    # Payloads for the four public notifications.
+    #
+    # Contract, identity, and lineage only. Domain data and extensions are excluded by
+    # construction rather than by filtering, because a notification payload reaches logs
+    # and APM by default and a fact's contents are the application's to decide about.
+    # Every call site uses the block form, so Rails' own :exception keys report failures
+    # and EventRail needs no separate failure event.
+    module Notifications
+      module_function
+
+      # The same keys, read from the private queue representation, for the one
+      # notification that fires before a typed event exists.
+      def payload_for_representation(hash)
+        metadata = hash["metadata"] || {}
+
+        {
+          event_type: hash["event_type"],
+          event_version: hash["event_version"],
+          event_id: metadata["id"],
+          source: metadata["source"],
+          correlation_id: metadata["correlation_id"],
+          causation_id: metadata["causation_id"]
+        }
+      end
+
+      def payload_for(event)
+        {
+          event_type: event.event_type,
+          event_version: event.version,
+          event_id: event.id,
+          source: event.source,
+          correlation_id: event.correlation_id,
+          causation_id: event.causation_id
+        }
+      end
+    end
+  end
+end

data/lib/event_rail/internal/portable_value.rb

@@ -0,0 +1,108 @@
+require "bigdecimal"
+require "date"
+
+module EventRail
+  module Internal
+    module PortableValue
+      module_function
+
+      RAW_SCALARS = [ NilClass, TrueClass, FalseClass, String, Integer, Float ].freeze
+      TYPED_SCALARS = [ BigDecimal, Date, DateTime, Time ].freeze
+
+      def raw(value, path: "value", depth: 0)
+        reject_record!(value, path: path)
+
+        case value
+        when *RAW_SCALARS
+          freeze_scalar(value, path: path)
+        when Array
+          check_depth!(depth, path: path)
+          value.each_with_index.map do |item, index|
+            raw(item, path: "#{path}[#{index}]", depth: depth + 1)
+          end.freeze
+        when Hash
+          check_depth!(depth, path: path)
+          value.each_with_object({}) do |(key, item), result|
+            unless key.is_a?(String)
+              raise CastingError, "#{path} must use string hash keys; got #{key.inspect}"
+            end
+            if key.start_with?(Limits::ACTIVE_JOB_RESERVED_KEY_PREFIX)
+              raise CastingError,
+                "#{path} key #{key.inspect} uses the #{Limits::ACTIVE_JOB_RESERVED_KEY_PREFIX.inspect} " \
+                "prefix Active Job reserves in its argument encoding"
+            end
+
+            frozen_key = key.dup.freeze
+            result[frozen_key] = raw(item, path: "#{path}.#{key}", depth: depth + 1)
+          end.freeze
+        else
+          raise CastingError, "#{path} contains unsupported #{value.class}"
+        end
+      end
+
+      def typed(value, path: "value")
+        reject_record!(value, path: path)
+
+        case value
+        when *RAW_SCALARS, *TYPED_SCALARS
+          freeze_scalar(value, path: path)
+        when Array, Hash
+          raw(value, path: path)
+        else
+          raise CastingError, "#{path} cast to unsupported #{value.class}"
+        end
+      end
+
+      # A written value has crossed no boundary yet, so this is a structural check
+      # of what a JSON encoder can carry rather than a trust decision.
+      def json_primitive?(value)
+        case value
+        when *RAW_SCALARS
+          !value.is_a?(Float) || value.finite?
+        when Array
+          value.all? { |item| json_primitive?(item) }
+        when Hash
+          value.all? { |key, item| key.is_a?(String) && json_primitive?(item) }
+        else
+          false
+        end
+      end
+
+      def literal_default?(value)
+        case value
+        when Proc, Method
+          false
+        when Array
+          value.all? { |item| literal_default?(item) }
+        when Hash
+          value.all? { |key, item| literal_default?(key) && literal_default?(item) }
+        else
+          !value.respond_to?(:call)
+        end
+      end
+
+      def reject_record!(value, path: "value")
+        global_id_value = value.class.name == "GlobalID" && value.respond_to?(:app) && value.respond_to?(:model_id)
+        return unless value.respond_to?(:to_global_id) || global_id_value
+
+        raise CastingError, "#{path} cannot contain records or GlobalID values"
+      end
+
+      def check_depth!(depth, path:)
+        return if depth < Limits::MAX_RAW_DEPTH
+
+        raise CastingError, "#{path} exceeds the maximum nesting depth of #{Limits::MAX_RAW_DEPTH}"
+      end
+      private_class_method :check_depth!
+
+      def freeze_scalar(value, path:)
+        if value.is_a?(Numeric) && value.respond_to?(:finite?) && !value.finite?
+          raise CastingError, "#{path} must contain a finite number"
+        end
+
+        value.is_a?(String) ? value.dup.freeze : value.freeze
+      end
+      private_class_method :freeze_scalar
+    end
+  end
+end

data/lib/event_rail/internal/registry.rb

@@ -0,0 +1,224 @@
+require "active_support/core_ext/class/subclasses"
+require "monitor"
+
+module EventRail
+  module Internal
+    # The subscriber registry: a pending list the macro appends to, and an immutable
+    # snapshot preparation seals from it.
+    #
+    # Publication reads the snapshot without taking the lock, so a concurrent rebuild
+    # can only ever hand a reader a complete old snapshot or a complete new one. The
+    # unprepared state is distinct from a prepared snapshot in which an event happens
+    # to have no subscribers: the first is a boot-order bug and raises, the second is a
+    # legitimate zero-delivery publication.
+    class Registry
+      CONVENTIONAL_ROOTS = %w[app/events app/jobs].freeze
+
+      Snapshot = Struct.new(:subscribers, :contracts, keyword_init: true) do
+        def subscribers_for(event_class)
+          subscribers[event_class] || EMPTY_SUBSCRIBERS
+        end
+
+        def event_class_for(event_type, version)
+          contracts[[ event_type, version ]]
+        end
+
+        def versions_of(event_type)
+          contracts.keys.filter_map { |type, version| version if type == event_type }
+        end
+      end
+
+      EMPTY_SUBSCRIBERS = [].freeze
+
+      @monitor = Monitor.new
+      @pending = []
+      @snapshot = nil
+      @building = false
+
+      class << self
+        # Appending is idempotent per job class: the macro may be called more than once
+        # in one body, and the declarations themselves live on the job class.
+        def declare(job_class)
+          @monitor.synchronize do
+            if @snapshot && !@building
+              raise DeclarationError,
+                "#{job_class} declared a subscription after EventRail finished preparing, so it would receive no " \
+                "deliveries. Move it under a conventional app/events or app/jobs root, or load it from an " \
+                "autoload-once path or plain require before application preparation."
+            end
+
+            @pending << job_class unless @pending.include?(job_class)
+          end
+        end
+
+        def snapshot
+          snapshot = @snapshot
+          return snapshot if snapshot
+
+          raise NotReadyError,
+            "EventRail has not prepared its subscriber registry yet; publication is only available after " \
+            "application preparation"
+        end
+
+        def prepared?
+          !@snapshot.nil?
+        end
+
+        def subscribers_for(event_class)
+          snapshot.subscribers_for(event_class)
+        end
+
+        # Reentrant, because eager loading a conventional root runs macros that call
+        # back into `declare`.
+        def prepare
+          @monitor.synchronize do
+            previously_building = @building
+            @building = true
+            begin
+              eager_load_conventional_roots
+              prune_stale_declarations
+              @snapshot = build_snapshot
+            ensure
+              @building = previously_building
+            end
+          end
+          @snapshot
+        end
+
+        # Internal: opens the pending list for declarations outside preparation. Used by
+        # preparation itself and by EventRail's own tests, which define subscriber
+        # fixtures after the host application has already been prepared.
+        def reopen
+          @monitor.synchronize do
+            previously_building = @building
+            @building = true
+            begin
+              yield
+            ensure
+              @building = previously_building
+            end
+          end
+        end
+
+        def reset!
+          @monitor.synchronize do
+            @pending = []
+            @snapshot = nil
+            @building = false
+          end
+        end
+
+        private
+          # Rails exposes concrete loader roots for the host and every engine through the
+          # main autoloader. Iterating `Rails::Engine.subclasses[*].paths["app/jobs"]`
+          # does not work: that path is not exposed that way.
+          def eager_load_conventional_roots
+            return unless defined?(Rails) && Rails.respond_to?(:autoloaders)
+
+            loader = Rails.autoloaders.main
+            return unless loader.respond_to?(:eager_load_dir)
+
+            loader.dirs.each do |dir|
+              next unless CONVENTIONAL_ROOTS.any? { |root| dir.end_with?("/#{root}") }
+              next unless Dir.exist?(dir)
+
+              begin
+                loader.eager_load_dir(dir)
+              rescue Zeitwerk::Error
+                # An ignored or unmanaged directory is a legitimate application choice,
+                # not a reason to fail preparation.
+                nil
+              end
+            end
+          end
+
+          # A reload replaces class objects while leaving the previous ones reachable
+          # from this list. An entry survives only if the constant its own name denotes
+          # is still this exact object, which is what distinguishes a live class from a
+          # reloaded class's discarded predecessor. The list is never cleared wholesale,
+          # because a declaration in non-reloadable code -- an autoload-once path, or
+          # plainly required lib code -- ran its macro once at require time and would be
+          # lost on the first rebuild.
+          def prune_stale_declarations
+            @pending.select! { |job_class| live?(job_class) }
+          end
+
+          def live?(klass)
+            name = klass.name
+            return false if name.nil?
+
+            resolved = begin
+              Object.const_get(name)
+            rescue NameError
+              nil
+            end
+
+            resolved.equal?(klass)
+          end
+
+          def build_snapshot
+            contracts = build_contracts
+            subscribers = {}
+
+            @pending.each do |job_class|
+              validate_subscriber!(job_class)
+
+              job_class.event_rail_subscriptions.each do |event_class|
+                next unless live?(event_class)
+
+                (subscribers[event_class] ||= []) << job_class
+              end
+            end
+
+            subscribers.each_value { |jobs| jobs.sort_by!(&:name) }
+            subscribers.transform_values!(&:freeze)
+
+            Snapshot.new(subscribers: subscribers.freeze, contracts: contracts).freeze
+          end
+
+          # Every discovered event class is validated here rather than at first
+          # construction, so a broken contract or identity declaration fails the boot
+          # that introduced it instead of the first publication that happens to hit it.
+          def build_contracts
+            discovered = EventRail::Event.descendants.select { |event_class| live?(event_class) }
+            concrete = discovered.select { |event_class| event_class.concrete? }
+
+            ContractIndex.build(concrete)
+          end
+
+          def validate_subscriber!(job_class)
+            unless job_class.instance_methods(false).include?(:perform) ||
+                job_class.private_instance_methods(false).include?(:perform)
+              raise DeclarationError,
+                "#{job_class} declares a subscription but does not define its own perform, so it is abstract"
+            end
+            unless job_class.subclasses.empty?
+              raise DeclarationError,
+                "#{job_class} declares a subscription and has subclasses " \
+                "(#{job_class.subclasses.map(&:to_s).sort.join(", ")}), so it is abstract; declare the " \
+                "subscription on each concrete job instead"
+            end
+            unless job_class.include?(EventRail::JobContext)
+              raise DeclarationError,
+                "#{job_class} declares a subscription but does not propagate logical context. Add " \
+                "`include EventRail::JobContext` to #{job_class} or to its base class."
+            end
+
+            validate_perform_arity!(job_class)
+          end
+
+          # Exactly one required positional parameter. A splat or a keyword signature
+          # would accept an event by accident and make the delivery contract depend on
+          # how the method happens to be written.
+          def validate_perform_arity!(job_class)
+            parameters = job_class.instance_method(:perform).parameters
+            unless parameters.map(&:first) == [ :req ]
+              raise DeclarationError,
+                "#{job_class}#perform must take exactly one required positional event parameter, " \
+                "not #{parameters.inspect}"
+            end
+          end
+      end
+    end
+  end
+end

data/lib/event_rail/internal/stamping.rb

@@ -0,0 +1,185 @@
+require "securerandom"
+
+module EventRail
+  module Internal
+    # Turns a proposal into a stamped fact: resolves source, selects logical identity,
+    # derives a retry-stable ID, fixes occurrence time, and installs lineage. Fanout
+    # is a separate concern layered on top of this.
+    module Stamping
+      module_function
+
+      Prepared = Struct.new(:event, :execution, :logical_key, :relayed, keyword_init: true) do
+        def relayed?
+          relayed
+        end
+      end
+
+      def prepare(event, key: nil)
+        unless event.is_a?(Event)
+          raise InvalidEvent, "#{event.inspect} is not an EventRail::Event"
+        end
+
+        return relay(event, key: key) if event.stamped?
+
+        validate_key!(key)
+        execution = Execution.current
+        logical_identity = resolve_logical_identity(event, key)
+        logical_key = [ event.event_type, event.version, Identity.encode_component(logical_identity) ].freeze
+
+        recorded = execution&.derives_identity? ? execution.record(logical_key) : nil
+        if recorded&.succeeded?
+          raise DuplicatePublicationError.new(
+            event_type: event.event_type, version: event.version, event_id: recorded.event.id
+          )
+        end
+
+        extensions = Extensions.merge!(Current.extensions, event.extensions, error: InvalidEvent)
+        detect_retry_mismatch!(event, recorded, extensions) if recorded
+
+        source = event.class.default_source
+        event_id = recorded&.event&.id || derive_id(event, execution, source, logical_identity)
+        occurred_at = event.occurred_at || recorded&.event&.occurred_at || default_occurred_at(execution)
+
+        stamped = event.send(
+          :__stamp__,
+          id: event_id,
+          source: source,
+          occurred_at: occurred_at,
+          correlation_id: Current.correlation_id || event_id,
+          causation_id: Current.message_id,
+          extensions: extensions
+        )
+
+        execution.record!(logical_key, event: stamped, succeeded: false) if execution&.derives_identity?
+
+        Prepared.new(event: stamped, execution: execution, logical_key: logical_key, relayed: false)
+      end
+
+      def succeeded!(prepared)
+        execution = prepared.execution
+        return unless execution&.derives_identity?
+
+        execution.record!(prepared.logical_key, event: prepared.event, succeeded: true)
+      end
+
+      # A relayed fact belongs to its origin. Its ID, source, occurrence time,
+      # correlation, and extensions are preserved, and the relaying application's own
+      # context extensions are deliberately not merged in: local baggage is not part of
+      # somebody else's event. Only a missing causation is filled, because the local
+      # message genuinely is what caused this relay.
+      def relay(event, key:)
+        unless key.nil?
+          raise PublicationError,
+            "#{event.event_type.inspect} already carries the event ID #{event.id.inspect}, so a publication " \
+            "key cannot apply to it"
+        end
+
+        execution = Execution.current
+        logical_key = [ event.event_type, event.version, Identity.encode_component(event.id) ].freeze
+
+        if execution&.derives_identity?
+          recorded = execution.record(logical_key)
+          if recorded&.succeeded?
+            raise DuplicatePublicationError.new(
+              event_type: event.event_type, version: event.version, event_id: event.id
+            )
+          end
+        end
+
+        relayed = if event.causation_id.nil? && Current.message_id
+          event.send(
+            :__stamp__,
+            id: event.id,
+            source: event.source,
+            occurred_at: event.occurred_at,
+            correlation_id: event.correlation_id,
+            causation_id: Current.message_id,
+            extensions: event.extensions
+          )
+        else
+          event
+        end
+
+        execution.record!(logical_key, event: relayed, succeeded: false) if execution&.derives_identity?
+
+        Prepared.new(event: relayed, execution: execution, logical_key: logical_key, relayed: true)
+      end
+      private_class_method :relay
+
+      # 1. An explicit event ID wins, which is the relay path above.
+      # 2. An explicit call-site key.
+      # 3. The event class's declared identity attributes.
+      # 4. A singleton marker, for the first publication of that type in an execution.
+      def resolve_logical_identity(event, key)
+        return key if key
+
+        declared = event.class.identity_by
+        return Identity::SINGLETON if declared.empty?
+
+        declared.map { |name| event.public_send(name) }
+      end
+      private_class_method :resolve_logical_identity
+
+      # A key spelled as an integer at one call site and as its decimal string at
+      # another would derive two identities for one fact, and nothing would report it.
+      def validate_key!(key)
+        return if key.nil?
+
+        unless key.is_a?(String) && !key.empty? && key.valid_encoding?
+          raise PublicationError, "publication key must be a non-empty string; got #{key.inspect}"
+        end
+        if key.bytesize > Limits::MAX_IDENTIFIER_BYTES
+          raise PublicationError, "publication key exceeds #{Limits::MAX_IDENTIFIER_BYTES} bytes"
+        end
+      end
+      private_class_method :validate_key!
+
+      def derive_id(event, execution, source, logical_identity)
+        return SecureRandom.uuid.freeze unless execution&.derives_identity?
+
+        unless source
+          raise InvalidMetadata, "source is required to publish #{event.class}"
+        end
+
+        Identity.derive(
+          source: source,
+          job_class: execution.job_class,
+          scope: execution.scope,
+          event_type: event.event_type,
+          version: event.version,
+          logical_identity: logical_identity
+        ).freeze
+      end
+      private_class_method :derive_id
+
+      # The logical publication time: this execution's start, so it is stable across
+      # the attempt's own retries, and never inherited from a cause, so a follow-up
+      # event is never timestamped earlier than the work that produced it.
+      def default_occurred_at(execution)
+        execution&.started_at || Timestamp.normalize(Time.now.utc, field: "occurred_at")
+      end
+      private_class_method :default_occurred_at
+
+      # Retrying a failed publication republishes the same fact, not merely the same
+      # identity. Choosing silently between the recorded payload and the new one would
+      # either discard data or hand new data an ID consumers already deduplicated on.
+      def detect_retry_mismatch!(event, recorded, extensions)
+        differing = []
+        differing << "payload" unless event.data == recorded.event.data
+        if event.occurred_at && event.occurred_at != recorded.event.occurred_at
+          differing << "occurred_at"
+        end
+        differing << "extensions" unless extensions == recorded.event.extensions
+        return if differing.empty?
+
+        raise RetryPayloadMismatchError.new(
+          event_type: event.event_type,
+          version: event.version,
+          event_id: recorded.event.id,
+          differing_fields: differing
+        )
+      end
+      private_class_method :detect_retry_mismatch!
+    end
+  end
+end