event_rail 0.1.0

data/lib/event_rail/job_context.rb

@@ -0,0 +1,124 @@
+require "active_support/concern"
+require "securerandom"
+
+module EventRail
+  # Opt a regular Active Job base class into logical context propagation:
+  #
+  #   class ApplicationJob < ActiveJob::Base
+  #     include EventRail::JobContext
+  #   end
+  #
+  # EventRail ships no initializer, install generator, or global prepend. Prepending
+  # every `ActiveJob::Base` would change serialization for jobs whose owners never
+  # asked, and editing `ApplicationJob` from a generator assumes there is exactly one
+  # and that it is unmodified. The explicit inclusion keeps ownership visible, and
+  # application preparation fails with a precise message when a declared subscriber
+  # is missing it.
+  module JobContext
+    extend ActiveSupport::Concern
+
+    # One reserved key in the job's serialized data, carrying only JSON primitives.
+    ENTRY_KEY = "event_rail_context".freeze
+    ENTRY_VERSION = 1
+    SUPPORTED_ENTRY_VERSIONS = [ ENTRY_VERSION ].freeze
+
+    included do
+      around_perform do |job, block|
+        job.send(:__event_rail_around_perform__, &block)
+      end
+    end
+
+    # The entry is established exactly once per job instance and then re-emitted
+    # unchanged. Reading ambient context here instead would lose lineage on the path
+    # this design depends on most: when `retry_on` retries, Active Job serializes
+    # *after* the surrounding perform callbacks have already restored the previous
+    # context, so an ambient read would generate a fresh root on every retry. The
+    # instance survives, because `retry_job` re-enqueues the same object.
+    def serialize
+      super.merge(ENTRY_KEY => __event_rail_entry__)
+    end
+
+    def deserialize(job_data)
+      super
+      @__event_rail_entry__ = __event_rail_read_entry__(job_data[ENTRY_KEY])
+    end
+
+    private
+      # A subscriber's logical message is the event it is handling rather than the job
+      # that delivers it, so the subscriber integration overrides this. A regular job
+      # has no delivered event and speaks for itself.
+      def __event_rail_delivered_event__
+        nil
+      end
+
+      def __event_rail_entry__
+        @__event_rail_entry__ ||= __event_rail_build_entry__
+      end
+
+      # A job queued before context integration was deployed has no entry, and must
+      # still run: it becomes the root of its own causal chain rather than failing
+      # deserialization.
+      def __event_rail_build_entry__
+        message_id = job_id || SecureRandom.uuid
+        originated_at = Current.originated_at || Time.now.utc
+
+        {
+          "v" => ENTRY_VERSION,
+          "message_id" => message_id,
+          "correlation_id" => Current.correlation_id || message_id,
+          "causation_id" => Current.message_id,
+          "originated_at" => Internal::Timestamp.written(originated_at),
+          "extensions" => Current.extensions
+        }
+      end
+
+      def __event_rail_read_entry__(raw)
+        return nil unless raw.is_a?(Hash)
+
+        version = raw["v"]
+        unless SUPPORTED_ENTRY_VERSIONS.include?(version)
+          raise UnsupportedFormatError.new(
+            format_version: version, supported_format_versions: SUPPORTED_ENTRY_VERSIONS
+          )
+        end
+
+        # The adapter owns the hash it handed us, and the entry is mutated during
+        # execution to record when the attempt started.
+        raw.dup
+      end
+
+      def __event_rail_around_perform__(&block)
+        entry = __event_rail_entry__
+        event = __event_rail_delivered_event__
+
+        # Recorded on the entry at the first attempt and re-emitted by every later
+        # serialization, which is what makes a default occurrence time stable across
+        # this job's Active Job retries rather than tracking the retry's own start.
+        entry["execution_started_at"] ||= Internal::Timestamp.written(Time.now.utc)
+        started_at = Internal::Timestamp.normalize(
+          entry["execution_started_at"], field: "execution_started_at"
+        )
+
+        message_id = event ? event.id : entry["message_id"]
+        correlation_id = event ? event.correlation_id : entry["correlation_id"]
+        causation_id = event ? event.causation_id : entry["causation_id"]
+        extensions = event ? event.extensions : Internal::Extensions.validate!(
+          entry["extensions"], error: InvalidContext
+        )
+
+        execution = Internal::Execution.new(
+          job_class: self.class.name, scope: message_id, started_at: started_at
+        )
+
+        Internal::Context.establish(
+          message_id: message_id,
+          correlation_id: correlation_id,
+          causation_id: causation_id,
+          originated_at: Internal::Timestamp.normalize(entry["originated_at"], field: "originated_at"),
+          extensions: extensions
+        ) do
+          Internal::Execution.wrap(execution) { block.call }
+        end
+      end
+  end
+end

data/lib/event_rail/limits.rb

@@ -0,0 +1,31 @@
+module EventRail
+  module Limits
+    MAX_IDENTIFIER_BYTES = 512
+    MAX_SOURCE_BYTES = 255
+    MAX_EVENT_TYPE_BYTES = 255
+    MAX_EXTENSION_ENTRIES = 32
+    MAX_EXTENSION_KEY_BYTES = 64
+    MAX_EXTENSION_VALUE_BYTES = 1_024
+    MAX_EXTENSIONS_BYTES = 8_192
+
+    # Raw portable structures are application-shaped, so they need a bound that
+    # fails during construction rather than as a stack overflow inside a recursive
+    # wire reconstruction on a worker.
+    MAX_RAW_DEPTH = 32
+
+    # Active Job's argument encoding claims this prefix for its own hash keys, so a
+    # payload key using it would either collide with an encoding key or survive as
+    # an unintended instruction to the decoder.
+    ACTIVE_JOB_RESERVED_KEY_PREFIX = "_aj_".freeze
+
+    RESERVED_EXTENSION_KEYS = %w[
+      id
+      source
+      occurred_at
+      correlation_id
+      causation_id
+      traceparent
+      tracestate
+    ].freeze
+  end
+end

data/lib/event_rail/metadata.rb

@@ -0,0 +1,94 @@
+module EventRail
+  class Metadata
+    attr_reader :id, :source, :occurred_at, :correlation_id, :causation_id, :extensions
+
+    def self.proposed(occurred_at: nil, extensions: {})
+      new(occurred_at: occurred_at, extensions: extensions, complete: false)
+    end
+
+    def self.complete(id:, source:, occurred_at:, correlation_id:, causation_id: nil, extensions: {})
+      new(
+        id: id,
+        source: source,
+        occurred_at: occurred_at,
+        correlation_id: correlation_id,
+        causation_id: causation_id,
+        extensions: extensions,
+        complete: true
+      )
+    end
+
+    def self.validate_source!(value)
+      validate_string!(value, field: "source", maximum: Limits::MAX_SOURCE_BYTES)
+    end
+
+    def self.validate_identifier!(value, field:, optional: false)
+      return if optional && value.nil?
+
+      validate_string!(value, field: field, maximum: Limits::MAX_IDENTIFIER_BYTES)
+    end
+
+    def self.validate_string!(value, field:, maximum:)
+      unless value.is_a?(String) && !value.empty? && value.valid_encoding?
+        raise InvalidMetadata, "#{field} must be a non-empty valid string"
+      end
+      if value.bytesize > maximum
+        raise InvalidMetadata, "#{field} exceeds #{maximum} bytes"
+      end
+
+      value
+    end
+    private_class_method :validate_string!
+
+    def initialize(id: nil, source: nil, occurred_at: nil, correlation_id: nil, causation_id: nil, extensions: {}, complete:)
+      if complete
+        self.class.validate_identifier!(id, field: "id")
+        self.class.validate_source!(source)
+        self.class.validate_identifier!(correlation_id, field: "correlation_id")
+        self.class.validate_identifier!(causation_id, field: "causation_id", optional: true)
+      elsif [ id, source, correlation_id, causation_id ].any?
+        raise InvalidMetadata, "local event metadata cannot contain identity, source, correlation, or causation"
+      end
+
+      @id = duplicate_and_freeze(id)
+      @source = duplicate_and_freeze(source)
+      @occurred_at = Internal::Timestamp.cast(occurred_at, field: "occurred_at")
+      if complete && @occurred_at.nil?
+        raise InvalidMetadata, "occurred_at is required for complete metadata"
+      end
+      @correlation_id = duplicate_and_freeze(correlation_id)
+      @causation_id = duplicate_and_freeze(causation_id)
+      @extensions = validate_extensions(extensions)
+      @complete = complete
+      freeze
+    end
+
+    def complete?
+      @complete
+    end
+
+    # Value equality, so two events carrying the same fact and the same lineage
+    # compare equal across a serialization boundary.
+    COMPARED_FIELDS = [ :id, :source, :occurred_at, :correlation_id, :causation_id, :extensions ].freeze
+
+    def ==(other)
+      other.instance_of?(self.class) &&
+        other.complete? == complete? &&
+        COMPARED_FIELDS.all? { |field| other.public_send(field) == public_send(field) }
+    end
+    alias_method :eql?, :==
+
+    def hash
+      ([ self.class, @complete ] + COMPARED_FIELDS.map { |field| public_send(field) }).hash
+    end
+
+    private
+      def duplicate_and_freeze(value)
+        value&.dup&.freeze
+      end
+
+      def validate_extensions(value)
+        Internal::Extensions.validate!(value, error: InvalidMetadata)
+      end
+  end
+end

data/lib/event_rail/portable_type.rb

@@ -0,0 +1,35 @@
+module EventRail
+  # Opt-in contract for a custom Active Model type used as an EventRail attribute
+  # type.
+  #
+  # Rails already defines `serialize` and `deserialize`, so this adds no vocabulary.
+  # What it adds is a stricter target: `ActiveModel::Type::Value#serialize` is
+  # documented as producing a value "usable by the database", and database drivers
+  # accept Date, Time, and BigDecimal objects. A queue is not a database. Active Job
+  # does not recurse into a custom serializer's output, so a Ruby object left there
+  # reaches the adapter raw, where a JSON-native adapter rejects the job and a JSON
+  # column stringifies it and loses precision.
+  #
+  # A type therefore promises that `serialize` returns a JSON primitive, array, or
+  # string-keyed hash, and that `deserialize` reconstructs the identical cast value
+  # from it. `portable_examples` is what makes the promise checkable: EventRail
+  # round-trips every example through JSON when the attribute is declared, so a type
+  # that cannot hold up fails at class definition instead of at the first enqueue.
+  #
+  #   class MoneyType < ActiveModel::Type::Value
+  #     include EventRail::PortableType
+  #
+  #     def cast(value) = value.is_a?(Money) ? value : Money.parse(value)
+  #     def serialize(value) = value&.to_s
+  #     def deserialize(value) = value && Money.parse(value)
+  #     def portable_examples = [ Money.new(0, "USD"), Money.new(1250, "EUR") ]
+  #   end
+  module PortableType
+    # Cast values covering every written shape the type can produce. At least one
+    # is required, and each must survive serialize, a JSON encoding cycle, and
+    # deserialize while comparing equal to the value it started as.
+    def portable_examples
+      raise NotImplementedError, "#{self.class} must define portable_examples"
+    end
+  end
+end

data/lib/event_rail/publication.rb

@@ -0,0 +1,33 @@
+module EventRail
+  # What `EventRail.publish` returns: the stamped fact, plus which subscribers took it
+  # and which deliberately declined it.
+  #
+  # Delivery outcome is not event metadata -- an event is the same fact regardless of
+  # who received it -- so it lives here instead. The skipped list is the part that
+  # matters operationally: a subscriber's own uniqueness, concurrency, or feature-flag
+  # callback aborting its enqueue is a decision, not a fault, and this is where an
+  # application can see it happened.
+  class Publication
+    attr_reader :event, :accepted_subscribers, :skipped_subscribers
+
+    def initialize(event:, accepted_subscribers:, skipped_subscribers:)
+      @event = event
+      @accepted_subscribers = accepted_subscribers.freeze
+      @skipped_subscribers = skipped_subscribers.freeze
+      freeze
+    end
+
+    def subscriber_count
+      accepted_subscribers.length + skipped_subscribers.length
+    end
+
+    def id
+      event.id
+    end
+
+    def inspect
+      "#<EventRail::Publication event=#{event.inspect} accepted=#{accepted_subscribers.length} " \
+        "skipped=#{skipped_subscribers.length}>"
+    end
+  end
+end

data/lib/event_rail/publish.rb

@@ -0,0 +1,88 @@
+require "active_support/notifications"
+
+module EventRail
+  class << self
+    # Publishes an event: stamps it with identity, source, occurrence time, and
+    # lineage, then calls ordinary `perform_later` on each declared subscriber.
+    #
+    #   publication = EventRail.publish(Orders::OrderPlaced.new(order_id: order.id))
+    #
+    # Individual enqueue calls, not `perform_all_later`. Bulk enqueue skips each job's
+    # own `enqueue` callbacks on several adapters, and those callbacks are exactly where
+    # an application puts uniqueness, concurrency, and feature-flag decisions that this
+    # design promises stay authoritative.
+    #
+    # Delivery is at-least-once. Jobs already accepted are not rolled back when a later
+    # subscriber's enqueue fails, and the retry repeats complete fanout under the same
+    # event ID, so a subscriber may see the same event more than once.
+    def publish(event, key: nil)
+      Internal::Transaction.check!
+
+      prepared = Internal::Stamping.prepare(event, key: key)
+      stamped = prepared.event
+      subscribers = Internal::Registry.subscribers_for(stamped.class)
+
+      accepted = []
+      skipped = []
+
+      ActiveSupport::Notifications.instrument("publish.event_rail", Internal::Notifications.payload_for(stamped)) do |payload|
+        payload[:subscriber_count] = subscribers.length
+
+        subscribers.each do |job_class|
+          enqueue_subscriber(job_class, stamped, accepted, skipped)
+        end
+
+        payload[:accepted] = accepted.length
+        payload[:skipped] = skipped.length
+      end
+
+      # Successful once every subscriber was either accepted or deliberately skipped. A
+      # skipped delivery is a decision, so treating it as a failure would make one
+      # subscriber's guard retry the publisher forever.
+      Internal::Stamping.succeeded!(prepared)
+
+      Publication.new(event: stamped, accepted_subscribers: accepted, skipped_subscribers: skipped)
+    end
+
+    private
+      # Three outcomes, not two. Active Job returns false both when an adapter reports
+      # failure and when an enqueue callback aborts, so the return value alone cannot
+      # tell a fault from a decision. The job instance can, through `enqueue_error`, and
+      # the block form of `perform_later` yields the job even when the call returns
+      # false.
+      def enqueue_subscriber(job_class, event, accepted, skipped)
+        payload = Internal::Notifications.payload_for(event).merge(job_class: job_class.name)
+
+        ActiveSupport::Notifications.instrument("enqueue_subscriber.event_rail", payload) do
+          job = nil
+
+          begin
+            result = job_class.perform_later(event) { |enqueued| job = enqueued }
+          rescue StandardError => cause
+            payload[:outcome] = "failed"
+            raise enqueue_error(event, job_class, accepted, skipped), cause: cause
+          end
+
+          if result == false && job&.enqueue_error
+            payload[:outcome] = "failed"
+            raise enqueue_error(event, job_class, accepted, skipped), cause: job.enqueue_error
+          elsif result == false
+            payload[:outcome] = "skipped"
+            skipped << job_class
+          else
+            payload[:outcome] = "accepted"
+            accepted << job_class
+          end
+        end
+      end
+
+      def enqueue_error(event, job_class, accepted, skipped)
+        EnqueueError.new(
+          event: event,
+          accepted_subscribers: accepted.dup,
+          skipped_subscribers: skipped.dup,
+          failed_subscriber: job_class
+        )
+      end
+  end
+end

data/lib/event_rail/railtie.rb

@@ -0,0 +1,15 @@
+module EventRail
+  class Railtie < ::Rails::Railtie
+    # Preparation, not an initializer: it has to run again on every reload, and it has
+    # to run after the main autoloader exists. Rails sets that loader up in a finisher
+    # that runs after config/initializers and runs prepare callbacks before
+    # eager_load!, so no reloadable constant outside a conventional root can already be
+    # loaded here -- which is exactly why one declared there raises later instead of
+    # silently receiving nothing.
+    config.to_prepare do
+      # Unqualified, so lexical lookup reaches the private Internal namespace that a
+      # qualified EventRail::Internal reference would be refused.
+      Internal::Registry.prepare
+    end
+  end
+end

data/lib/event_rail/subscriptions.rb

@@ -0,0 +1,59 @@
+module EventRail
+  # The class macro that declares a subscription. Extended onto `ActiveJob::Base`, so
+  # it is available on any ordinary job:
+  #
+  #   class Billing::OnOrderPlacedJob < ApplicationJob
+  #     subscribes_to Orders::OrderPlaced
+  #
+  #     def perform(event)
+  #       Billing.charge(order_id: event.order_id, idempotency_key: event.id)
+  #     end
+  #   end
+  #
+  # Only class methods are added, and nothing about serialization or execution
+  # changes for a job that never calls the macro. It is available on every job rather
+  # than only on jobs that include `EventRail::JobContext` so that a subscriber
+  # missing that inclusion fails application preparation with a precise message
+  # instead of a bare NoMethodError on the macro.
+  module Subscriptions
+    # Declares the exact event classes this job handles. The relationship is recorded
+    # for preparation to validate: `perform` is usually defined after this line, and
+    # whether this class has subclasses is not knowable until everything is loaded, so
+    # only what can be judged immediately is judged here.
+    def subscribes_to(*event_classes)
+      if event_classes.empty?
+        raise DeclarationError, "#{self} must name at least one event class to subscribe to"
+      end
+
+      own = (@event_rail_subscriptions ||= [])
+
+      event_classes.each do |event_class|
+        unless event_class.is_a?(Class) && event_class < EventRail::Event
+          raise DeclarationError,
+            "#{self} cannot subscribe to #{event_class.inspect}, which is not an EventRail::Event class"
+        end
+        if own.include?(event_class)
+          raise DeclarationError, "#{self} already declares a subscription to #{event_class}"
+        end
+
+        own << event_class
+      end
+
+      Internal::Registry.declare(self)
+      include Internal::SubscriberExecution unless include?(Internal::SubscriberExecution)
+
+      event_rail_subscriptions
+    end
+
+    # This class's own declarations. Deliberately not inherited: a subclass of a
+    # subscriber is a different job, and silently registering it as a second
+    # subscriber would double every delivery.
+    def event_rail_subscriptions
+      (@event_rail_subscriptions || []).dup.freeze
+    end
+
+    def event_rail_subscriber?
+      !(@event_rail_subscriptions || []).empty?
+    end
+  end
+end

data/lib/event_rail/version.rb

@@ -0,0 +1,3 @@
+module EventRail
+  VERSION = "0.1.0"
+end

data/lib/event_rail.rb

@@ -0,0 +1,52 @@
+require "active_job"
+require "active_model"
+require "active_support"
+require "rails/railtie"
+
+require "event_rail/version"
+require "event_rail/errors"
+require "event_rail/limits"
+require "event_rail/portable_type"
+require "event_rail/internal/portable_value"
+require "event_rail/internal/extensions"
+require "event_rail/internal/types"
+require "event_rail/internal/attribute_record"
+require "event_rail/data"
+require "event_rail/internal/timestamp"
+require "event_rail/metadata"
+require "event_rail/event"
+require "event_rail/internal/contract_index"
+require "event_rail/internal/identity"
+require "event_rail/internal/execution"
+require "event_rail/current"
+require "event_rail/internal/context"
+require "event_rail/job_context"
+require "event_rail/internal/notifications"
+require "event_rail/internal/subscriber_execution"
+require "event_rail/subscriptions"
+require "event_rail/internal/registry"
+require "event_rail/internal/stamping"
+require "event_rail/contract"
+require "event_rail/envelope"
+require "event_rail/internal/event_serializer"
+require "event_rail/internal/transaction"
+require "event_rail/publication"
+require "event_rail/publish"
+require "event_rail/railtie"
+
+# The subscription macro is class-level only: it changes nothing about serialization
+# or execution for a job that never calls it. Registering the hook here rather than in
+# an initializer means it is in place before Active Job loads, in a Rails application
+# and in a plain Ruby process alike.
+ActiveSupport.on_load(:active_job) do
+  extend EventRail::Subscriptions
+
+  # Registering here rather than in an initializer keeps the serializer available to a
+  # plain Ruby process too, and it is registered exactly once because the load hook runs
+  # once.
+  ActiveJob::Serializers.add_serializers(EventRail.const_get(:Internal)::EventSerializer)
+end
+
+module EventRail
+  private_constant :Internal
+end