event_rail 0.1.0

data/lib/event_rail/internal/attribute_record.rb

@@ -0,0 +1,272 @@
+require "active_model/attributes"
+require "active_model/validations"
+
+module EventRail
+  module Internal
+    class AttributeRecord
+      # Deliberately not ActiveModel::Model: that bundle also brings Conversion and
+      # Access, whose to_model, to_key, to_param, to_partial_path, persisted?, slice
+      # and values_at are view and form concerns. They are meaningless on an
+      # immutable historical fact and would become public API at 1.0.
+      include ActiveModel::Attributes
+      include ActiveModel::AttributeAssignment
+      include ActiveModel::Validations
+
+      DEFAULT_NOT_GIVEN = Object.new.freeze
+
+      class << self
+        def attribute(name, cast_type = nil, default: DEFAULT_NOT_GIVEN, array: false, **options)
+          attribute_name = name.to_s
+          validate_attribute_name!(attribute_name)
+
+          type = Types.resolve(cast_type, array: array, options: options)
+
+          if default.equal?(DEFAULT_NOT_GIVEN)
+            super(attribute_name, type)
+          else
+            unless PortableValue.literal_default?(default)
+              raise DeclarationError, "#{self} attribute #{attribute_name.inspect} cannot use a callable default"
+            end
+
+            super(attribute_name, type, default: type.cast(default))
+          end
+        end
+
+        def reserved_attribute_names
+          %w[attributes data errors valid?].freeze
+        end
+
+        def record_error_class
+          InvalidData
+        end
+
+        private
+          def validate_attribute_name!(name)
+            if reserved_attribute_names.include?(name)
+              raise DeclarationError, "#{self} cannot declare reserved attribute #{name.inspect}"
+            end
+
+            # Redeclaring an existing attribute is legitimate; its readers are ours.
+            return if attribute_types.key?(name)
+
+            shadowed = [ name, "#{name}=" ].find { |candidate| shadows_behavior?(candidate) }
+            return unless shadowed
+
+            raise DeclarationError,
+              "#{self} cannot declare attribute #{name.inspect} because #{shadowed.inspect} is already defined"
+          end
+
+          # A reader can only shadow behavior a caller could have reached, so public
+          # and protected methods are the boundary. Ruby defines a large private
+          # vocabulary on every object -- format, select, open, p, raise -- and those
+          # are ordinary domain words that no reader can shadow, because no caller
+          # could have invoked them through the receiver. The record's own private
+          # helpers are the exception: those are reached internally, so a reader
+          # replacing one would break this class from the inside.
+          def shadows_behavior?(name)
+            return true if method_defined?(name)
+            return false unless private_method_defined?(name)
+
+            owner = instance_method(name).owner
+            owner.name.to_s.start_with?("EventRail")
+          end
+
+          # Untrusted input: casts, validates, canonicalizes and freezes. State the
+          # caller already derived, such as reconstructed metadata, is installed
+          # before initialize runs, so no sentinel rides on the public signature.
+          #
+          # Trusted input arrives in written form and is read back through each
+          # declared type's `deserialize` before assignment, which is what lets a
+          # nested record preserve fields this version does not declare. Casting then
+          # sees values it already accepts, so the strict door stays strict without a
+          # second, laxer parser beside it.
+          def __event_rail_build__(declared, unknown: {}, state: {}, trusted: false)
+            values = trusted ? deserialize_declared(declared) : declared
+
+            record = allocate
+            state.each { |ivar, value| record.instance_variable_set(ivar, value) }
+            record.instance_variable_set(
+              :@unknown_attributes, PortableValue.raw(unknown, path: "unknown attributes")
+            )
+            record.send(:initialize, values)
+            record
+          end
+
+          # Partition is by declaration, so a field a newer producer added stays
+          # opaque payload without a reader instead of failing the reconstruction.
+          def __event_rail_reconstruct__(portable, state: {})
+            unless portable.is_a?(Hash) && portable.keys.all? { |key| key.is_a?(String) }
+              raise record_error_class, "trusted #{self} data must be a string-keyed hash"
+            end
+
+            known_names = attribute_names
+            declared, unknown = portable.partition { |name, _value| known_names.include?(name) }.map(&:to_h)
+            __event_rail_build__(declared, unknown: unknown, state: state, trusted: true)
+          end
+
+          def deserialize_declared(declared)
+            types = attribute_types
+
+            declared.each_with_object({}) do |(name, value), result|
+              result[name] = begin
+                types[name].deserialize(value)
+              rescue Error => error
+                raise error.class.new("attribute #{name.inspect}: #{error.message}"), cause: error
+              end
+            end
+          end
+
+          # Trusted in-process copy: the source is an instance of this class whose
+          # payload is already cast, validated, canonicalized and deeply frozen.
+          # Varying state the payload does not depend on cannot invalidate it, so
+          # nothing needs recomputing.
+          def __event_rail_copy__(source, state: {})
+            copy = allocate
+            source.instance_variables.each do |ivar|
+              copy.instance_variable_set(ivar, source.instance_variable_get(ivar))
+            end
+            state.each { |ivar, value| copy.instance_variable_set(ivar, value) }
+            copy.errors
+            copy.freeze
+          end
+      end
+
+      def initialize(attributes = nil, **keyword_attributes)
+        input = normalize_input(attributes, keyword_attributes)
+        declared, local_unknown = partition_attributes(input)
+
+        unless local_unknown.empty?
+          raise record_error_class, unknown_attributes_message(local_unknown)
+        end
+
+        # ActiveModel::Attributes#initialize takes no arguments; assignment is
+        # AttributeAssignment's job, which ActiveModel::API used to chain for us.
+        super()
+        assign_attributes(declared) unless declared.empty?
+        self.class.attribute_names.each { |name| public_send(name) }
+
+        @unknown_attributes ||= PortableValue.raw({}, path: "unknown attributes")
+        validate_record!
+        @data = build_data
+        @attributes.freeze
+        freeze
+      rescue Error
+        raise
+      rescue ActiveModel::UnknownAttributeError, ArgumentError => error
+        raise record_error_class, error.message
+      end
+
+      # The written projection of the whole payload: JSON primitives, arrays, and
+      # string-keyed hashes, including fields a newer producer added that this version
+      # does not declare. This is the single form the private queue representation and
+      # the public envelope both read, and it is built once per instance rather than
+      # once per serialization.
+      def data
+        @data
+      end
+
+      # Two records of one class that carry the same payload are the same value. The
+      # comparison is over the written projection rather than the cast attributes so
+      # that a record reconstructed from a queue matches the one it was written from,
+      # and so that unknown preserved fields participate.
+      def ==(other)
+        other.instance_of?(self.class) && other.data == data
+      end
+      alias_method :eql?, :==
+
+      def hash
+        [ self.class, data ].hash
+      end
+
+      # An immutable value has no meaningful copy, and Active Model's own
+      # initialize_dup deep-dups into an unfrozen attribute set while clearing
+      # errors, which would otherwise hand back a mutable record whose readers
+      # disagree with its payload view.
+      def dup
+        frozen? ? self : super
+      end
+
+      def clone(freeze: nil)
+        frozen? ? self : super
+      end
+
+      # Validations already ran once, during construction. Active Model would
+      # re-run them here, which raises on a frozen record on Rails 7.2 and can
+      # report a published fact as invalid on later versions when a validation
+      # depends on external state.
+      def valid?(context = nil)
+        frozen? ? true : super
+      end
+
+      # Object#inspect prints every instance variable, and Active Job logs each
+      # argument's inspect by default, so an unmanaged representation publishes
+      # domain payload into ordinary application logs.
+      def inspect
+        "#<#{self.class.name || self.class.inspect}>"
+      end
+
+      private
+        def attribute_method?(attribute_name)
+          self.class.attribute_names.include?(attribute_name)
+        end
+
+        def normalize_input(attributes, keyword_attributes)
+          unless attributes.nil? || attributes.is_a?(Hash)
+            raise record_error_class, "attributes must be supplied as a hash or keywords"
+          end
+
+          combined = (attributes || {}).merge(keyword_attributes) do |key|
+            raise record_error_class, "attribute #{key.inspect} was supplied more than once"
+          end
+
+          combined.each_with_object({}) do |(key, value), result|
+            unless key.is_a?(String) || key.is_a?(Symbol)
+              raise record_error_class, "attribute names must be strings or symbols"
+            end
+
+            normalized = key.to_s
+            if result.key?(normalized)
+              raise record_error_class, "attribute #{normalized.inspect} was supplied more than once"
+            end
+
+            result[normalized] = value
+          end
+        end
+
+        def unknown_attributes_message(unknown)
+          "unknown attributes: #{unknown.keys.sort.join(", ")}"
+        end
+
+        def partition_attributes(input)
+          known_names = self.class.attribute_names
+          input.partition { |name, _value| known_names.include?(name) }.map(&:to_h)
+        end
+
+        def validate_record!
+          return if valid?
+
+          error_hash = errors.to_hash(true).transform_values { |messages| messages.map(&:dup).freeze }.freeze
+          raise record_error_class.new(record_validation_message, validation_errors: error_hash)
+        end
+
+        # Declared names in declaration order, then preserved unknown fields, so the
+        # written form of one logical payload is byte-identical between processes.
+        def build_data
+          types = self.class.attribute_types
+          declared = self.class.attribute_names.to_h do |name|
+            [ -name, types[name].serialize(public_send(name)) ]
+          end
+
+          declared.merge(@unknown_attributes).freeze
+        end
+
+        def record_error_class
+          self.class.record_error_class
+        end
+
+        def record_validation_message
+          "#{self.class} is invalid: #{errors.full_messages.join(", ")}"
+        end
+    end
+  end
+end

data/lib/event_rail/internal/context.rb

@@ -0,0 +1,32 @@
+module EventRail
+  module Internal
+    # Installs lineage for the duration of a block and restores exactly what was
+    # there before.
+    #
+    # The restore is manual rather than `CurrentAttributes#set`, because the values
+    # have to survive nested in-process execution. The Rails executor resets current
+    # attributes around `ActiveJob::Base.execute`, but a job performed inside another
+    # -- the test adapter, the inline adapter, any `perform_now` -- never passes
+    # through the executor, so without an explicit restore the inner job's lineage
+    # would still be installed when the outer job resumes.
+    module Context
+      module_function
+
+      FIELDS = [ :message_id, :correlation_id, :causation_id, :originated_at, :extensions ].freeze
+
+      def establish(message_id:, correlation_id:, causation_id:, originated_at:, extensions:)
+        previous = FIELDS.to_h { |field| [ field, Current.public_send(field) ] }
+
+        Current.message_id = message_id
+        Current.correlation_id = correlation_id
+        Current.causation_id = causation_id
+        Current.originated_at = originated_at
+        Current.extensions = extensions
+
+        yield
+      ensure
+        previous.each { |field, value| Current.public_send(:"#{field}=", value) }
+      end
+    end
+  end
+end

data/lib/event_rail/internal/contract_index.rb

@@ -0,0 +1,28 @@
+module EventRail
+  module Internal
+    class ContractIndex
+      def self.build(event_classes)
+        index = {}
+
+        event_classes.each do |event_class|
+          unless event_class.is_a?(Class) && event_class < EventRail::Event
+            raise InvalidContract, "#{event_class.inspect} is not an EventRail::Event class"
+          end
+
+          key = event_class.contract_key
+          if index.key?(key)
+            raise DuplicateContractError.new(
+              event_type: key.first,
+              version: key.last,
+              event_classes: [ index.fetch(key), event_class ]
+            )
+          end
+
+          index[key] = event_class
+        end
+
+        index.freeze
+      end
+    end
+  end
+end

data/lib/event_rail/internal/event_serializer.rb

@@ -0,0 +1,148 @@
+module EventRail
+  module Internal
+    # The private Active Job representation of an event.
+    #
+    # Private means EventRail owns it entirely: its shape is not public API, no
+    # application should read or write it, and it may change under the staging
+    # discipline below. The public boundary is `EventRail::Envelope`.
+    #
+    # Every value written is a JSON primitive, array, or string-keyed hash. That is not
+    # a stylistic choice: `ObjectSerializer#serialize` is `@template.merge(hash)` and
+    # `ActiveJob::Arguments.serialize` does not recurse into the result, so a `Date`,
+    # `Time`, or `BigDecimal` left here would reach the queue adapter raw -- where a
+    # JSON-native adapter rejects the job and a JSON column stringifies it and loses
+    # precision. The per-type `serialize` contract is what guarantees it, and
+    # `event.data` is already the whole payload in that form.
+    #
+    # FORMAT_VERSION governs the structure of this hash and nothing else. It is
+    # deliberately independent of an event's schema version, and it does not govern the
+    # canonical encoding of individual values -- that encoding is shared with the public
+    # envelope and evolves as a public compatibility contract, not as a private format
+    # bump.
+    #
+    # Evolving it is a staged, read-before-write deployment: a release that reads both
+    # the old and the new format ships everywhere first, a later release starts writing
+    # the new one, and the old reader is removed only once every queued old-format
+    # message is drained or expired.
+    class EventSerializer < ActiveJob::Serializers::ObjectSerializer
+      FORMAT_VERSION = 1
+      SUPPORTED_FORMAT_VERSIONS = [ FORMAT_VERSION ].freeze
+
+      FORMAT_KEY = "format"
+      TYPE_KEY = "event_type"
+      VERSION_KEY = "event_version"
+      METADATA_KEY = "metadata"
+      DATA_KEY = "data"
+
+      ID = "id"
+      SOURCE = "source"
+      OCCURRED_AT = "occurred_at"
+      CORRELATION_ID = "correlation_id"
+      CAUSATION_ID = "causation_id"
+      EXTENSIONS = "extensions"
+
+      # Every Event subclass, so applications register nothing.
+      def klass
+        EventRail::Event
+      end
+
+      # Read through methods rather than the constants directly, so a staged release can
+      # subclass this to widen what it reads before anything writes the newer form. The
+      # staging fixtures rely on that, and so would a real format migration.
+      def format_version
+        FORMAT_VERSION
+      end
+
+      def supported_format_versions
+        SUPPORTED_FORMAT_VERSIONS
+      end
+
+      def serialize(event)
+        unless event.stamped?
+          raise InvalidEvent,
+            "#{event.class} has not been published, so it cannot be enqueued; pass the event EventRail.publish " \
+            "returned rather than the proposal"
+        end
+
+        super(
+          FORMAT_KEY => format_version,
+          TYPE_KEY => event.event_type,
+          VERSION_KEY => event.version,
+          METADATA_KEY => {
+            ID => event.id,
+            SOURCE => event.source,
+            OCCURRED_AT => Timestamp.written(event.occurred_at),
+            CORRELATION_ID => event.correlation_id,
+            CAUSATION_ID => event.causation_id,
+            EXTENSIONS => event.extensions
+          },
+          DATA_KEY => event.data
+        )
+      end
+
+      def deserialize(hash)
+        written_format = hash[FORMAT_KEY]
+        unless supported_format_versions.include?(written_format)
+          raise UnsupportedFormatError.new(
+            format_version: written_format, supported_format_versions: supported_format_versions
+          )
+        end
+
+        event_type = hash[TYPE_KEY]
+        version = hash[VERSION_KEY]
+        event_class = resolve!(event_type, version)
+
+        payload = Notifications.payload_for_representation(hash).merge(format_version: written_format)
+
+        ActiveSupport::Notifications.instrument("deserialize.event_rail", payload) do
+          event_class.send(:__reconstruct__, data: read_data(hash), metadata: read_metadata(hash))
+        end
+      end
+
+      private
+        # Resolved through the prepared registry, never by constantizing the type name.
+        # An unknown type and an unregistered version are different operational problems:
+        # the first says this worker does not know the contract at all, the second says it
+        # knows it at other versions and a producer is ahead of or behind this deploy.
+        def resolve!(event_type, version)
+          snapshot = Registry.snapshot
+          event_class = snapshot.event_class_for(event_type, version)
+          return event_class if event_class
+
+          known_versions = snapshot.versions_of(event_type)
+          if known_versions.empty?
+            raise UnknownEventTypeError.new(event_type: event_type, version: version)
+          end
+
+          raise UnsupportedEventVersionError.new(
+            event_type: event_type, version: version, supported_versions: known_versions
+          )
+        end
+
+        def read_metadata(hash)
+          metadata = hash[METADATA_KEY]
+          unless metadata.is_a?(Hash)
+            raise SerializationError, "malformed EventRail representation: metadata must be a hash"
+          end
+
+          Metadata.complete(
+            id: metadata[ID],
+            source: metadata[SOURCE],
+            occurred_at: metadata[OCCURRED_AT],
+            correlation_id: metadata[CORRELATION_ID],
+            causation_id: metadata[CAUSATION_ID],
+            extensions: metadata[EXTENSIONS] || {}
+          )
+        end
+
+        def read_data(hash)
+          data = hash[DATA_KEY]
+          unless data.is_a?(Hash)
+            raise SerializationError, "malformed EventRail representation: data must be a hash"
+          end
+
+          data
+        end
+    end
+  end
+end

data/lib/event_rail/internal/execution.rb

@@ -0,0 +1,86 @@
+require "active_support/isolated_execution_state"
+
+module EventRail
+  module Internal
+    # One publishing execution: a job attempt, or an application boundary block.
+    #
+    # Publication state belongs to exactly one attempt. It cannot live in
+    # `ActiveSupport::CurrentAttributes`, because the Rails executor resets those
+    # around `ActiveJob::Base.execute` and nested in-process execution gets no reset,
+    # so a subscriber performed inside its publisher -- the test adapter, the inline
+    # adapter, any `perform_now` -- would share the publisher's map and could have a
+    # legitimate publication rejected as a duplicate in test while succeeding in
+    # production.
+    #
+    # It cannot live in `ActiveSupport::ExecutionContext[:job]` either, which is the
+    # mechanism this design originally named. `ActiveJob::Execution#_perform_job`
+    # assigns that key and never restores it, so after a nested `perform_now` returns
+    # it still points at the inner job: the outer job's next publication would read
+    # the inner job's state and derive identity from the inner job's scope. The stack
+    # here is pushed and popped by EventRail itself, in an ensure, so a nested
+    # execution restores its parent exactly.
+    class Execution
+      STACK_KEY = :event_rail_executions
+
+      class << self
+        def stack
+          ActiveSupport::IsolatedExecutionState[STACK_KEY] ||= []
+        end
+
+        def current
+          stack.last
+        end
+
+        def push(execution)
+          stack.push(execution)
+          execution
+        end
+
+        def pop(execution)
+          stack.pop if stack.last.equal?(execution)
+        end
+
+        def wrap(execution)
+          push(execution)
+          yield execution
+        ensure
+          pop(execution)
+        end
+      end
+
+      attr_reader :job_class, :scope, :started_at
+
+      # `job_class` is nil for a boundary block. That is what separates the two: a
+      # boundary supplies an occurrence time and lineage but derives no identity, so
+      # an event published there still receives a random ID, and no duplicate check
+      # applies outside a job attempt.
+      def initialize(job_class: nil, scope: nil, started_at: nil)
+        @job_class = job_class
+        @scope = scope
+        @started_at = started_at
+        @publications = {}
+      end
+
+      def derives_identity?
+        !job_class.nil? && !scope.nil?
+      end
+
+      def record(key)
+        @publications[key]
+      end
+
+      def record!(key, event:, succeeded:)
+        @publications[key] = Record.new(event: event, succeeded: succeeded)
+      end
+
+      # What one logical publication looked like the last time this attempt tried it.
+      # Retaining the failed case is what lets the same attempt retry complete fanout
+      # under the identity it already stamped, instead of manufacturing a second one.
+      Record = Struct.new(:event, :succeeded, keyword_init: true) do
+        def succeeded?
+          succeeded
+        end
+      end
+    end
+  end
+end

data/lib/event_rail/internal/extensions.rb

@@ -0,0 +1,69 @@
+module EventRail
+  module Internal
+    # Extensions are durable baggage, so their bounds are the same wherever they are
+    # installed: on an event, on a logical context, or merged from both. One
+    # implementation keeps the limits from drifting apart between those doors, and the
+    # caller supplies the error class so the message names the thing being built.
+    module Extensions
+      module_function
+
+      EMPTY = {}.freeze
+
+      def validate!(value, error:)
+        return EMPTY if value.nil? || (value.is_a?(Hash) && value.empty?)
+
+        unless value.is_a?(Hash)
+          raise error, "extensions must be a hash of string keys and values"
+        end
+        if value.length > Limits::MAX_EXTENSION_ENTRIES
+          raise error, "extensions exceed #{Limits::MAX_EXTENSION_ENTRIES} entries"
+        end
+
+        total_bytes = 0
+        result = value.each_with_object({}) do |(key, item), output|
+          unless key.is_a?(String) && item.is_a?(String)
+            raise error, "extension keys and values must be strings"
+          end
+          if Limits::RESERVED_EXTENSION_KEYS.include?(key) || key.start_with?("eventrail.")
+            raise error, "extension key #{key.inspect} is reserved"
+          end
+          if key.empty? || !key.valid_encoding? || key.bytesize > Limits::MAX_EXTENSION_KEY_BYTES
+            raise error, "extension key #{key.inspect} is invalid or too long"
+          end
+          if !item.valid_encoding? || item.bytesize > Limits::MAX_EXTENSION_VALUE_BYTES
+            raise error, "extension value for #{key.inspect} is invalid or too long"
+          end
+
+          total_bytes += key.bytesize + item.bytesize
+          output[key.dup.freeze] = item.dup.freeze
+        end
+
+        if total_bytes > Limits::MAX_EXTENSIONS_BYTES
+          raise error, "extensions exceed #{Limits::MAX_EXTENSIONS_BYTES} encoded bytes"
+        end
+
+        result.freeze
+      end
+
+      # Repeating a key with the same value is how a nested scope says "still true".
+      # Repeating it with a different value is an attempt to rewrite baggage an
+      # ancestor installed, which would make the same key mean different things at
+      # different depths of one flow.
+      def merge!(inherited, added, error:)
+        return inherited if added.nil? || added.empty?
+
+        validated = validate!(added, error: error)
+        return validated if inherited.nil? || inherited.empty?
+
+        conflicts = validated.filter_map do |key, value|
+          key if inherited.key?(key) && inherited.fetch(key) != value
+        end
+        unless conflicts.empty?
+          raise error, "extension #{conflicts.sort.join(", ")} already has a different value in this context"
+        end
+
+        validate!(inherited.merge(validated), error: error)
+      end
+    end
+  end
+end