sourced-message 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12ddf9298bf827a4f20e9f2db6b9edababd24efa73323326e5cd5ff6bbedebc1
-  data.tar.gz: a88ab37ddb627868b20cd9a03615334a01d1f957fc3dedae25db4486623b983f
+  metadata.gz: b8202b720a3a57bf15a429a136797186c2bc8bd2721a7539e2f08495e7078923
+  data.tar.gz: 6532b0db8f33fb6aa9ba4d585d5b0424fd089be4917e994f4a1abd341db132b4
 SHA512:
-  metadata.gz: 154e306175767857b9471c5700fe12ec3f73c17292af5c30826e2f61afa0dc217853e56950cddbf3decf8b38c38f5837e3cad76a822c6078cfd8904ef912093b
-  data.tar.gz: 0640b5e2560fa1dfd331ee8b015dde0b5195bf1ec55efaa1cb0e98cf4b3713ca8544b4bc784495cb09f08d32d12bc2dc4c60977b60df99b021bf6f71a6e63c76
+  metadata.gz: ba7bafee643414f03b642074c521257fb731f663dc653d6ddedb3c6ca2d26304e727d7c719fac830d196aee3e1086aed22d126759c4671a3242fcc6c89fff5a8
+  data.tar.gz: 5f979cf196b3d6e0bc3b37ddc5b85f0a9284b1d8fad4a15a877ca835b18a747e49d9c1e5a5a0ad0b4acaaffe8b7bbb02411ee34f888445a30f6f3835c6eb267b

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [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.0'
 
     EMPTY_ARRAY = [].freeze
 
@@ -43,10 +43,15 @@ 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)
     LaxTime = Types::Time | Types::String.build(::Time, :parse).policy(:rescue, ::ArgumentError)
@@ -57,6 +62,9 @@ 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.
@@ -200,6 +208,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.0
 platform: ruby
 authors:
 - Ismael Celis