sourced-message 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12ddf9298bf827a4f20e9f2db6b9edababd24efa73323326e5cd5ff6bbedebc1
-  data.tar.gz: a88ab37ddb627868b20cd9a03615334a01d1f957fc3dedae25db4486623b983f
+  metadata.gz: 5f851a99f35af7389e8aeaa9a62e174c9c76fe83c7123ccf245160672250534b
+  data.tar.gz: af633b34af3853e032e2b4735394dec70b03bcce4e19b1dacd54f80cf76382f3
 SHA512:
-  metadata.gz: 154e306175767857b9471c5700fe12ec3f73c17292af5c30826e2f61afa0dc217853e56950cddbf3decf8b38c38f5837e3cad76a822c6078cfd8904ef912093b
-  data.tar.gz: 0640b5e2560fa1dfd331ee8b015dde0b5195bf1ec55efaa1cb0e98cf4b3713ca8544b4bc784495cb09f08d32d12bc2dc4c60977b60df99b021bf6f71a6e63c76
+  metadata.gz: 46637a045f56cd99c1ead9dba880d6d846a58106d7d8200c35606fc21d484f92514f310cad4fc1f3ea20298c9e356a875069a4c076c9a40c73a7cc7ebdc1be85
+  data.tar.gz: 83972e23b181caa04596cb6235a5fe0aec375bf6795967a12157c1b104c1b5e380c37a246afff29ce57c3fa909847ade958567b0b90ff1af2831c7c922353846

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+- `Message::Registry` raises `DuplicateTypeError` when two classes with different names
+  claim one type string, instead of silently replacing the registered class. Registering
+  a type again is still allowed when the names are equal (a code reloader redefining a
+  constant) or either class is anonymous (throwaway classes in specs; a constant in an
+  anonymous module counts as anonymous until the module is named). `.define`
+  registers a class before it's assigned to its constant, so the comparison waits until
+  the new class has a name: the next registration of the type, its lookup (`[]`,
+  `Message.from`, codec `decode`) or `#all` (codec `compile!`) raises.
+
+## [0.5.0]
+
+- `Message#tags`: an envelope attribute (`Types::Tags`, Symbol keys and String values,
+  empty by default) holding key/value pairs a store can index alongside the payload's,
+  without the message class declaring them. Codecs encode and decode it with the rest
+  of the envelope.
+- `#with_tags(**tags)` returns a copy with tags merged in, values stringified. It raises
+  `TagConflictError` when a tag names a payload attribute with a different value.
+- `#correlate` leaves the target's tags alone: tags never pass on to messages produced
+  in reaction, unlike metadata.
+- `Sourced::Message::VERSION` is now `0.5.0`.
+
 ## [0.4.0]
 
 - Requires plumb 0.4, whose codecs rewrite Hash keys like values: `#encode` now emits

data/README.md

@@ -9,11 +9,12 @@ A message is a [Plumb](https://github.com/ismasan/plumb)-typed value object with
 - an auto-generated `id` and `created_at` timestamp
 - `causation_id` / `correlation_id` for tracing causal chains across processes
 - arbitrary `metadata`
+- `tags`: key/value pairs for a store to index, outside the payload
 - a global **type registry** that can reconstruct any message from a plain hash — handy for transports, queues and event stores
 - **codecs** that serialize messages to JSON or to form params and back, preserving the types each payload declares
 - scheduling helpers (`#at` / `#in`) for delayed messages
 
-Messages are immutable: every "mutating" method (`#with_payload`, `#with_metadata`, `#at`, `#correlate`) returns a copy.
+Messages are immutable: every "mutating" method (`#with_payload`, `#with_metadata`, `#with_tags`, `#at`, `#correlate`) returns a copy.
 
 ## Installation
 
@@ -69,6 +70,7 @@ msg.id            # => "5f6e..."  (auto-generated UUID)
 msg.type          # => "course.created"
 msg.created_at    # => 2026-06-06 12:00:00 ... (defaults to Time.now)
 msg.metadata      # => {}
+msg.tags          # => {}
 msg.causation_id  # => same as msg.id by default
 msg.correlation_id # => same as msg.id by default
 ```
@@ -165,7 +167,7 @@ codec = Sourced::Message::JSONCodec.default.compile!
 
 encoded = codec.encode(msg)
 # => { id: "8f1c…", causation_id: "8f1c…", correlation_id: "8f1c…",
-#      created_at: "2026-09-01T10:00:00.000000+01:00", metadata: {}, type: "course.created",
+#      created_at: "2026-09-01T10:00:00.000000+01:00", metadata: {}, tags: {}, type: "course.created",
 #      payload: { course_name: "Ruby 101", starts_on: "2026-09-01", level: "beginner" } }
 
 decoded = codec.decode(JSON.parse(JSON.dump(encoded), symbolize_names: true))
@@ -321,6 +323,11 @@ Messages are immutable. Use the `#with_*` helpers to derive new copies:
 tagged = msg.with_metadata(channel: 'web', user_id: '42')
 tagged.metadata # => { channel: 'web', user_id: '42' }
 
+# Merge tags: String values, outside the payload (keeps the same id).
+# A tag naming a payload attribute must match its value, or it raises TagConflictError.
+scoped = msg.with_tags(school_id: 's1')
+scoped.tags # => { school_id: 's1' }
+
 # Override payload attributes
 updated = msg.with_payload(seats: 25)
 updated.payload.seats # => 25
@@ -329,7 +336,7 @@ updated.payload.course_name # => "Ruby 101" (unchanged)
 
 ### Correlation: tracing causal chains
 
-`#correlate` links one message as the cause of another. It returns a copy of the target with `causation_id` set to the source's `id` and `correlation_id` propagated from the source. Metadata from both messages is merged.
+`#correlate` links one message as the cause of another. It returns a copy of the target with `causation_id` set to the source's `id` and `correlation_id` propagated from the source. Metadata from both messages is merged. Tags are not: the copy keeps the target's own.
 
 ```ruby
 trigger = EnrollStudent.new(payload: { student_id: '42' })

data/lib/sourced/message.rb

@@ -22,7 +22,7 @@ module Sourced
   # +Sourced::Message.registry[type]+ resolves a type registered under any
   # subclass. Resolve from this root to see the whole tree.
   class Message < Plumb::Types::Data
-    VERSION = '0.4.0'
+    VERSION = '0.5.1'
 
     EMPTY_ARRAY = [].freeze
 
@@ -43,12 +43,19 @@ module Sourced
                   Array[Any.defer { JSONValue }] | Hash[Symbol, Any.defer { JSONValue }]
 
       Metadata = Hash[Symbol, JSONValue]
+
+      # Key/value pairs a store can index alongside the payload's. Values are Strings.
+      Tags = Hash[Symbol, String]
     end
 
     # Raised by {.from} when a type string isn't registered.
     UnknownMessageError = Class.new(ArgumentError)
+    # Raised by {#with_tags} when a tag names a payload attribute with a different value.
+    TagConflictError = Class.new(ArgumentError)
     # Raised by {#at} when a message would be scheduled in the past.
     PastMessageDateError = Class.new(ArgumentError)
+    # Raised by {Registry} when two classes with different names claim one type string.
+    DuplicateTypeError = Class.new(ArgumentError)
     LaxTime = Types::Time | Types::String.build(::Time, :parse).policy(:rescue, ::ArgumentError)
 
     attribute :id, Types::AutoUUID
@@ -57,14 +64,25 @@ module Sourced
     attribute? :correlation_id, Types::UUID::V4
     attribute :created_at, LaxTime.default { Time.now }
     attribute :metadata, Types::Metadata.default(Plumb::BLANK_HASH)
+    # Envelope, not payload: {#correlate} leaves the target's tags alone, so they
+    # never pass on to messages produced in reaction.
+    attribute :tags, Types::Tags.default(Plumb::BLANK_HASH)
     attribute :payload, Types::Static[nil]
 
     # Lookup table mapping type strings to message subclasses.
+    #
+    # Registering a type again replaces its class: a code reloader redefines a
+    # constant, and specs define throwaway anonymous messages reusing type
+    # strings. Two classes with different permanent names claiming one type are
+    # a bug, and raise {DuplicateTypeError}. {.define} registers a class before
+    # it's assigned to its constant, so the replaced class is kept until its
+    # successor has a name, and compared on the next registration or lookup.
     class Registry
       # @param message_class [Class] the root message class for this registry
       def initialize(message_class)
         @message_class = message_class
         @lookup = {}
+        @replaced = {}
       end
 
       # @return [Array<String>] registered type strings
@@ -77,7 +95,14 @@ module Sourced
       #
       # @param key [String] message type string
       # @param klass [Class] message subclass
+      # @raise [DuplicateTypeError] if a class with a different name holds the type
       def []=(key, klass)
+        check!(key)
+        previous = @lookup[key]
+        if previous && named(previous) && !previous.equal?(klass)
+          duplicate!(key, previous, klass) if named(klass) && named(klass) != named(previous)
+          @replaced[key] = previous unless named(klass)
+        end
         @lookup[key] = klass
       end
 
@@ -86,7 +111,9 @@ module Sourced
       #
       # @param key [String] message type string
       # @return [Class, nil]
+      # @raise [DuplicateTypeError] if a class with a different name holds the type
       def [](key)
+        check!(key) unless @replaced.empty?
         klass = lookup[key]
         return klass if klass
 
@@ -101,9 +128,11 @@ module Sourced
       #
       # @return [Enumerator<Class>] if no block given
       # @yield [Class] each registered message class
+      # @raise [DuplicateTypeError] if a class with a different name holds a type
       def all(&block)
         return enum_for(:all) unless block
 
+        @replaced.keys.each { |key| check!(key) }
         lookup.each_value(&block)
         subclasses.each { |c| c.registry.all(&block) }
       end
@@ -111,6 +140,29 @@ module Sourced
       private
 
       attr_reader :lookup, :message_class
+
+      # Compare the class a type replaced with the one holding it, once the latter has a name.
+      def check!(key)
+        replaced = @replaced[key]
+        return unless replaced
+
+        current = @lookup[key]
+        return unless named(current)
+
+        @replaced.delete(key)
+        duplicate!(key, replaced, current) unless named(current) == named(replaced)
+      end
+
+      # A class's permanent name. A constant set in an anonymous module has a
+      # temporary one (+"#<Class:0x...>::Foo"+) until the module is named.
+      def named(klass)
+        name = klass.name
+        name unless name.nil? || name.start_with?('#<')
+      end
+
+      def duplicate!(key, registered, klass)
+        raise DuplicateTypeError, "message type #{key.inspect} is claimed by both #{registered.name} and #{klass.name}"
+      end
     end
 
     # @return [Registry] the message type registry for this class
@@ -200,6 +252,27 @@ module Sourced
       with(metadata: metadata.merge(meta))
     end
 
+    # A copy with +tags+ merged in, values stringified.
+    #
+    # @param tags [Hash{Symbol => #to_s}]
+    # @return [Message]
+    # @raise [TagConflictError] if a tag names a payload attribute with a different value
+    def with_tags(**tags)
+      return self if tags.empty?
+
+      tags = tags.transform_values(&:to_s)
+      declared = self.class.payload_attribute_names
+      tags.each do |key, value|
+        next unless declared.include?(key)
+        next if payload[key].to_s == value
+
+        raise TagConflictError,
+              "#{type} tag #{key}: #{value.inspect} conflicts with its payload value #{payload[key].inspect}"
+      end
+
+      with(tags: self.tags.merge(tags))
+    end
+
     def with_payload(attrs = {})
       hash = to_h
       (hash[:payload] ||= {}).merge!(attrs)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sourced-message
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Ismael Celis