event_rail 0.1.0

data/lib/event_rail/envelope.rb

@@ -0,0 +1,123 @@
+module EventRail
+  # The format-neutral boundary an application's own codec reads and writes.
+  #
+  #   envelope = EventRail::Envelope.of(published.event)
+  #   payload  = MyJsonCodec.encode(envelope)   # the application owns the bytes
+  #
+  # EventRail produces no bytes and mandates no format. It exposes the logical fields --
+  # contract, metadata, and the event's portable data projection -- and stops there,
+  # because canonical bytes, a universal hash, and a content type are decisions that
+  # belong to whoever owns the transport. There is deliberately no `to_h` that could
+  # become a de facto wire format.
+  #
+  # `data` is the portable projection, so a codec never receives a `Date`, a
+  # `BigDecimal`, or a nested Ruby object it would have to decide how to canonicalize.
+  # Every value is a JSON primitive, array, or string-keyed hash, including fields a
+  # newer producer added that the local class does not declare.
+  class Envelope
+    attr_reader :contract, :metadata, :data
+
+    def self.of(event)
+      unless event.is_a?(Event)
+        raise InvalidEnvelope, "#{event.inspect} is not an EventRail::Event"
+      end
+      unless event.stamped?
+        raise InvalidEnvelope, "#{event.class} has not been published, so it has no durable metadata to export"
+      end
+
+      new(contract: Contract.of(event.class), metadata: event.metadata, data: event.data)
+    end
+
+    def initialize(contract:, metadata:, data:)
+      unless contract.is_a?(Contract)
+        raise InvalidEnvelope, "contract must be an EventRail::Contract; got #{contract.inspect}"
+      end
+      unless metadata.is_a?(Metadata) && metadata.complete?
+        raise InvalidEnvelope, "metadata must be complete EventRail::Metadata; got #{metadata.inspect}"
+      end
+      unless data.is_a?(Hash) && data.keys.all? { |key| key.is_a?(String) }
+        raise InvalidEnvelope, "data must be a string-keyed hash"
+      end
+
+      @contract = contract
+      @metadata = metadata
+      @data = data.freeze
+      freeze
+    end
+
+    def event_type
+      contract.event_type
+    end
+
+    def version
+      contract.version
+    end
+
+    def id
+      metadata.id
+    end
+
+    def source
+      metadata.source
+    end
+
+    def occurred_at
+      metadata.occurred_at
+    end
+
+    def correlation_id
+      metadata.correlation_id
+    end
+
+    def causation_id
+      metadata.causation_id
+    end
+
+    def extensions
+      metadata.extensions
+    end
+
+    # The only public trusted-reconstruction entry point, and it takes the class
+    # explicitly.
+    #
+    # V1 defines no resolver protocol and never constantizes anything from the
+    # envelope: a type name arriving over a network must not be able to name a Ruby
+    # constant. An application maps a contract to a class with its own allowlist before
+    # calling this:
+    #
+    #   ALLOWED = { [ "orders.order_placed", 1 ] => Orders::OrderPlaced }.freeze
+    #   event_class = ALLOWED.fetch([ envelope.event_type, envelope.version ])
+    #   envelope.to_event(event_class)
+    #
+    # The internal queue registry deliberately does not authorize external input: it
+    # exists so a worker can read its own organization's queue, which is a different
+    # trust question from accepting a message off a shared bus.
+    def to_event(event_class)
+      unless event_class.is_a?(Class) && event_class < Event
+        raise InvalidEnvelope, "#{event_class.inspect} is not an EventRail::Event class"
+      end
+      unless event_class.event_type == event_type && event_class.version == version
+        raise InvalidEnvelope,
+          "#{event_class} declares #{Contract.of(event_class)} but this envelope carries #{contract}"
+      end
+
+      event_class.send(:__reconstruct__, data: data, metadata: metadata)
+    end
+
+    def ==(other)
+      other.instance_of?(self.class) && other.contract == contract &&
+        other.metadata == metadata && other.data == data
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [ self.class, contract, metadata, data ].hash
+    end
+
+    # Contract and identity only: an envelope carries domain data, and a diagnostic
+    # string is not the place for it.
+    def inspect
+      "#<EventRail::Envelope #{contract} id=#{id.inspect} source=#{source.inspect}>"
+    end
+  end
+end

data/lib/event_rail/errors.rb

@@ -0,0 +1,196 @@
+module EventRail
+  # Every error EventRail raises descends from this, so an application can rescue
+  # the library without naming its internals. Each subclass exposes stable
+  # diagnostic fields only -- contracts, identifiers, and application classes --
+  # never a registry, serializer, job instance, or other internal object, and each
+  # preserves the cause it wrapped so the original backtrace stays reachable.
+  class Error < StandardError
+  end
+
+  # Something about a class body is wrong, so it is wrong for every instance: a
+  # reserved or shadowing attribute name, a callable default, an attribute type with
+  # no written form, an invalid subscription.
+  class DeclarationError < Error
+  end
+
+  # A value cannot become the declared type without discarding information, or is not
+  # portable at all.
+  class CastingError < Error
+  end
+
+  class InvalidData < Error
+    attr_reader :validation_errors
+
+    def initialize(message = "nested data is invalid", validation_errors: {})
+      @validation_errors = validation_errors.freeze
+      super(message)
+    end
+  end
+
+  class InvalidEvent < Error
+    attr_reader :validation_errors
+
+    def initialize(message = "event is invalid", validation_errors: {})
+      @validation_errors = validation_errors.freeze
+      super(message)
+    end
+  end
+
+  class InvalidMetadata < Error
+  end
+
+  class InvalidContract < Error
+  end
+
+  class DuplicateContractError < InvalidContract
+    attr_reader :event_type, :version, :event_classes
+
+    def initialize(event_type:, version:, event_classes:)
+      @event_type = event_type
+      @version = version
+      @event_classes = event_classes.freeze
+      names = event_classes.map { |event_class| event_class.name || event_class.inspect }
+      super("duplicate event contract #{event_type.inspect} version #{version}: #{names.join(", ")}")
+    end
+  end
+
+  # A logical context cannot be established: a nested scope tried to replace lineage
+  # it inherited, or an identifier or extension is out of bounds.
+  class InvalidContext < Error
+  end
+
+  # An external envelope cannot be trusted into a typed event.
+  class InvalidEnvelope < Error
+  end
+
+  # Publication ran before the application finished preparing, so the subscriber
+  # snapshot does not exist yet. Deliberately distinct from a prepared application
+  # whose event happens to have no subscribers.
+  class NotReadyError < Error
+  end
+
+  # A subscriber was handed an argument it cannot treat as its declared event.
+  class UnexpectedEventError < Error
+    attr_reader :job_class, :expected_event_classes, :received_class
+
+    def initialize(message, job_class:, expected_event_classes:, received_class:)
+      @job_class = job_class
+      @expected_event_classes = expected_event_classes.freeze
+      @received_class = received_class
+      super(message)
+    end
+  end
+
+  class SerializationError < Error
+  end
+
+  # The representation names a format this release does not read. Raised before any
+  # subscriber code runs, and distinct from an event schema version problem: the
+  # format version governs the representation's structure, not the event's contract.
+  class UnsupportedFormatError < SerializationError
+    attr_reader :format_version, :supported_format_versions
+
+    def initialize(format_version:, supported_format_versions:)
+      @format_version = format_version
+      @supported_format_versions = supported_format_versions.freeze
+      super(
+        "unsupported EventRail serialization format #{format_version.inspect}; " \
+        "this release reads #{supported_format_versions.join(", ")}"
+      )
+    end
+  end
+
+  class UnknownEventTypeError < SerializationError
+    attr_reader :event_type, :version
+
+    def initialize(event_type:, version:)
+      @event_type = event_type
+      @version = version
+      super("no registered event class for #{event_type.inspect} version #{version.inspect}")
+    end
+  end
+
+  class UnsupportedEventVersionError < SerializationError
+    attr_reader :event_type, :version, :supported_versions
+
+    def initialize(event_type:, version:, supported_versions:)
+      @event_type = event_type
+      @version = version
+      @supported_versions = supported_versions.freeze
+      super(
+        "event #{event_type.inspect} version #{version.inspect} is not registered; " \
+        "registered versions are #{supported_versions.sort.join(", ")}"
+      )
+    end
+  end
+
+  class PublicationError < Error
+  end
+
+  # The same logical fact was published twice in one execution after the first
+  # publication succeeded.
+  class DuplicatePublicationError < PublicationError
+    attr_reader :event_type, :version, :event_id
+
+    def initialize(event_type:, version:, event_id:)
+      @event_type = event_type
+      @version = version
+      @event_id = event_id
+      super(
+        "#{event_type.inspect} version #{version} with this logical identity was already published " \
+        "as #{event_id.inspect} in this execution"
+      )
+    end
+  end
+
+  # A retry resolved to a recorded failed publication whose fact differs from the one
+  # now being published. Neither choice is safe -- fanning out the recorded payload
+  # discards the new data, and reusing the recorded ID for new data lies to every
+  # consumer that deduplicates on it -- so publication refuses instead.
+  class RetryPayloadMismatchError < PublicationError
+    attr_reader :event_type, :version, :event_id, :differing_fields
+
+    def initialize(event_type:, version:, event_id:, differing_fields:)
+      @event_type = event_type
+      @version = version
+      @event_id = event_id
+      @differing_fields = differing_fields.freeze
+      super(
+        "retrying publication of #{event_type.inspect} version #{version} as #{event_id.inspect} " \
+        "but #{differing_fields.sort.join(", ")} differ from the recorded event"
+      )
+    end
+  end
+
+  # Publication happened inside an open application database transaction. Both queue
+  # deferral settings are wrong there, in opposite directions: a deferred enqueue
+  # cannot report its own failure, and an immediate one announces a fact a rollback
+  # then contradicts.
+  class TransactionalPublicationError < PublicationError
+    def initialize(message = nil)
+      super(
+        message ||
+          "cannot publish inside an open database transaction; publish after the transaction commits"
+      )
+    end
+  end
+
+  # Fanout could not complete. The accepted and skipped lists are what an operator
+  # needs to know which subscribers may already have work queued, because publication
+  # is at-least-once and the retry will enqueue all of them again.
+  class EnqueueError < PublicationError
+    attr_reader :event, :accepted_subscribers, :skipped_subscribers, :failed_subscriber
+
+    def initialize(event:, accepted_subscribers:, skipped_subscribers:, failed_subscriber:, message: nil)
+      @event = event
+      @accepted_subscribers = accepted_subscribers.freeze
+      @skipped_subscribers = skipped_subscribers.freeze
+      @failed_subscriber = failed_subscriber
+      super(
+        message ||
+          "could not enqueue #{failed_subscriber} for #{event.event_type.inspect} version #{event.version} " \
+          "(#{event.id}); #{accepted_subscribers.length} accepted, #{skipped_subscribers.length} skipped"
+      )
+    end
+  end
+end

data/lib/event_rail/event.rb

@@ -0,0 +1,258 @@
+module EventRail
+  class Event < Internal::AttributeRecord
+    VALUE_NOT_GIVEN = Object.new.freeze
+
+    # Metadata an application may supply, but only as an explicit keyword: reaching
+    # it through attribute data is how forged lineage would arrive from a params hash.
+    KEYWORD_METADATA_NAMES = %w[extensions occurred_at].freeze
+
+    # Metadata an application may never supply. These are derived during publication
+    # or arrive through validated reconstruction.
+    DERIVED_METADATA_NAMES = %w[causation_id correlation_id id source].freeze
+
+    RESERVED_ATTRIBUTE_NAMES = %w[
+      attributes
+      contract
+      correlation_id
+      causation_id
+      data
+      default_source
+      errors
+      event_type
+      extensions
+      id
+      identity_by
+      metadata
+      occurred_at
+      payload
+      source
+      stamped?
+      type
+      valid?
+      version
+    ].freeze
+
+    class << self
+      def event_type(value = VALUE_NOT_GIVEN)
+        return @event_type if value.equal?(VALUE_NOT_GIVEN)
+
+        unless value.is_a?(String) && !value.empty? && value.valid_encoding?
+          raise DeclarationError, "event_type must be a non-empty valid string"
+        end
+        if value.bytesize > Limits::MAX_EVENT_TYPE_BYTES
+          raise DeclarationError, "event_type exceeds #{Limits::MAX_EVENT_TYPE_BYTES} bytes"
+        end
+
+        @event_type = value.dup.freeze
+      end
+
+      def version(value = VALUE_NOT_GIVEN)
+        return @event_version if value.equal?(VALUE_NOT_GIVEN)
+
+        unless value.is_a?(Integer) && value.positive?
+          raise DeclarationError, "version must be a positive integer"
+        end
+
+        @event_version = value
+      end
+
+      def default_source(value = VALUE_NOT_GIVEN)
+        if value.equal?(VALUE_NOT_GIVEN)
+          return @default_source if instance_variable_defined?(:@default_source)
+          return superclass.default_source if superclass.respond_to?(:default_source)
+
+          return
+        end
+
+        Metadata.validate_source!(value)
+        @default_source = value.dup.freeze
+      rescue InvalidMetadata => error
+        raise DeclarationError, error.message
+      end
+
+      def identity_by(*attribute_names)
+        return (@identity_attributes || []).dup.freeze if attribute_names.empty?
+
+        names = attribute_names.map(&:to_s)
+        if names.empty? || names.any?(&:empty?) || names.uniq.length != names.length
+          raise DeclarationError, "identity_by requires unique non-empty attribute names"
+        end
+
+        @identity_attributes = names.map(&:freeze).freeze
+      end
+
+      # A class that declares either half of the contract is meant to be published and
+      # must declare both. One that declares neither is an application's own abstract
+      # base -- `class ApplicationEvent < EventRail::Event` -- and is not a registrable
+      # contract, so discovery skips it rather than failing preparation over it.
+      def concrete?
+        !event_type.nil? || !version.nil?
+      end
+
+      def validate_definition!
+        unless event_type && version
+          raise InvalidContract, "#{self} must explicitly declare event_type and version"
+        end
+
+        identity_by.each do |attribute_name|
+          unless attribute_names.include?(attribute_name)
+            raise InvalidContract, "#{self} identity attribute #{attribute_name.inspect} is not declared"
+          end
+          unless attribute_types[attribute_name].is_a?(Internal::Types::Scalar)
+            raise InvalidContract, "#{self} identity attribute #{attribute_name.inspect} must be scalar"
+          end
+        end
+
+        true
+      end
+
+      def contract_key
+        validate_definition!
+        [ event_type, version ].freeze
+      end
+
+      def reserved_attribute_names
+        (super + RESERVED_ATTRIBUTE_NAMES).uniq.freeze
+      end
+
+      def record_error_class
+        InvalidEvent
+      end
+
+      private
+        # Not public API: reconstruction of a trusted representation belongs to the
+        # private queue serializer and to validated envelope reconstruction, which
+        # supply metadata they have already checked. An application that could call
+        # this could install any lineage it liked.
+        def __reconstruct__(data:, metadata:)
+          validate_definition!
+          unless metadata.is_a?(Metadata) && metadata.complete?
+            raise InvalidMetadata, "trusted reconstruction requires complete metadata"
+          end
+
+          __event_rail_reconstruct__(data, state: { :@metadata => metadata })
+        end
+    end
+
+    attr_reader :metadata
+
+    def initialize(attributes = nil, occurred_at: nil, extensions: {}, **payload)
+      self.class.validate_definition!
+
+      # Trusted reconstruction installs complete metadata before initialize runs.
+      @metadata ||= Metadata.proposed(occurred_at: occurred_at, extensions: extensions)
+      super(attributes, **payload)
+
+      validate_local_identity! unless @metadata.complete?
+    end
+
+    def event_type
+      self.class.event_type
+    end
+
+    def version
+      self.class.version
+    end
+
+    def id
+      metadata.id
+    end
+
+    def source
+      metadata.source
+    end
+
+    def occurred_at
+      metadata.occurred_at
+    end
+
+    def correlation_id
+      metadata.correlation_id
+    end
+
+    def causation_id
+      metadata.causation_id
+    end
+
+    def extensions
+      metadata.extensions
+    end
+
+    def stamped?
+      metadata.complete?
+    end
+
+    # Metadata participates, so a proposal and the stamped event copied from it are
+    # different values: one is a fact with an identity and the other is a request to
+    # record one.
+    def ==(other)
+      super && other.metadata == metadata
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [ self.class, data, metadata ].hash
+    end
+
+    # Contract and metadata only: domain payload and extensions stay out of
+    # diagnostics, including Active Job argument logging.
+    def inspect
+      "#<#{self.class.name || self.class.inspect} type=#{event_type.inspect} version=#{version.inspect} " \
+        "id=#{id.inspect} source=#{source.inspect} occurred_at=#{occurred_at.inspect}>"
+    end
+
+    private
+      # Not public API: stamping installs the identity and lineage that make an event
+      # a published fact, and publication is the only thing entitled to do that.
+      def __stamp__(id:, source: nil, occurred_at: nil, correlation_id:, causation_id: nil, extensions: nil)
+        resolved_source = source || self.class.default_source
+        raise InvalidMetadata, "source is required to stamp #{self.class}" unless resolved_source
+
+        stamped_metadata = Metadata.complete(
+          id: id,
+          source: resolved_source,
+          occurred_at: occurred_at || metadata.occurred_at,
+          correlation_id: correlation_id,
+          causation_id: causation_id,
+          extensions: extensions || metadata.extensions
+        )
+
+        # A metadata-only copy. Reconstructing through the validating constructor
+        # would re-cast and re-validate payload this instance already canonicalized,
+        # and would rebuild every nested data object, for no change to the payload.
+        self.class.send(:__event_rail_copy__, self, state: { :@metadata => stamped_metadata })
+      end
+
+      # A declared identity attribute that is nil cannot produce a canonical value, so
+      # the event can never be published. The local constructor is the strict door and
+      # the only place whose backtrace points at the code that left the field empty.
+      # Trusted reconstruction stays permissive: an external event of this contract may
+      # legitimately omit a field, and it arrives with an identity already assigned.
+      def validate_local_identity!
+        missing = self.class.identity_by.select { |name| public_send(name).nil? }
+        return if missing.empty?
+
+        raise InvalidEvent,
+          "#{self.class} declares #{missing.sort.join(", ")} as logical identity, so it cannot be nil"
+      end
+
+      def unknown_attributes_message(unknown)
+        names = unknown.keys
+        keyword_only = names & KEYWORD_METADATA_NAMES
+        derived = names & DERIVED_METADATA_NAMES
+        return super if keyword_only.empty? && derived.empty?
+
+        parts = []
+        unless keyword_only.empty?
+          parts << "#{keyword_only.sort.join(", ")} must be supplied as a keyword argument, not as attribute data"
+        end
+        unless derived.empty?
+          parts << "#{derived.sort.join(", ")} cannot be set locally; event metadata is derived during " \
+            "publication or supplied through validated reconstruction"
+        end
+        remaining = names - keyword_only - derived
+        parts << "unknown attributes: #{remaining.sort.join(", ")}" unless remaining.empty?
+        parts.join("; ")
+      end
+  end
+end