sourced-message 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c32c4b5ea1020c0623e0f572d67a529a70630e21dd9d865a43386c4ca318915b
-  data.tar.gz: b1bf6ccf2eadf06ea8c5bf301f692a520bb9cb84de37c07a5a340a0395177ff5
+  metadata.gz: b8202b720a3a57bf15a429a136797186c2bc8bd2721a7539e2f08495e7078923
+  data.tar.gz: 6532b0db8f33fb6aa9ba4d585d5b0424fd089be4917e994f4a1abd341db132b4
 SHA512:
-  metadata.gz: c9d6eb69097f9e6f70df79786f8a285c638d7a985f762ba15d70463109058b5884117d838242834db8771a1ee6996434695d5ab4a4dac4d9809a2d25c0456ffa
-  data.tar.gz: a1b78a345ee0f8463372e729d9cce17ad28ce9c9da6a2d137da72c174ed10d668148018b7fdb7f13529d2c6d9db78a14f8401e0d976781457f95ec52944998ba
+  metadata.gz: ba7bafee643414f03b642074c521257fb731f663dc653d6ddedb3c6ca2d26304e727d7c719fac830d196aee3e1086aed22d126759c4671a3242fcc6c89fff5a8
+  data.tar.gz: 5f979cf196b3d6e0bc3b37ddc5b85f0a9284b1d8fad4a15a877ca835b18a747e49d9c1e5a5a0ad0b4acaaffe8b7bbb02411ee34f888445a30f6f3835c6eb267b

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [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
+  String keys (`{'type' => ..., 'payload' => {'name' => ...}}`), and decoders accept
+  String or Symbol keys. `JSON.dump` output is unchanged.
+- `Codec#decode` reads the envelope's `type` and `id` under either key form, so
+  `decode(encode(message))` works without a JSON round trip.
+- `metadata` is typed as `Types::Metadata`: Symbol keys and `Types::JSONValue` values
+  (String, Numeric, boolean, nil, and Arrays/Symbol-keyed Hashes of those, at any depth).
+  Codecs now restore nested metadata keys as Symbols. A non-JSON value (a Time, a
+  Symbol) makes the message invalid and fails `#encode`, where `JSON.dump` used to
+  stringify it silently.
+- `Sourced::Message::VERSION` is now `0.4.0`.
+
 ## [0.3.0]
 
 - Add `Sourced::Message#correlation_type`, the type counterpart of `correlation_id`:

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/codec.rb

@@ -182,23 +182,27 @@ module Sourced
       # Rebuild a message from decoded attributes. An unknown type raises: a process
       # reading types it doesn't know about is missing the class.
       #
-      # @param attrs [Hash] symbol-keyed message attributes
+      # @param attrs [Hash] message attributes, String- (as #encode emits them) or Symbol-keyed
       # @return [Sourced::Message]
       # @raise [UnknownMessageError] if the type isn't in the registry
       # @raise [UnregisteredTypeError] if the type was not compiled
       # @raise [DecodeError] if the attributes don't satisfy the schema
       def decode(attrs)
-        type = attrs[:type]
+        type = envelope(attrs, :type)
+        id = envelope(attrs, :id)
         klass = @registry[type]
-        raise UnknownMessageError, "Unknown message type: #{label(type, attrs[:id])}" unless klass
+        raise UnknownMessageError, "Unknown message type: #{label(type, id)}" unless klass
 
-        build(klass, attrs, pair(type, attrs[:id]).decoder)
+        build(klass, attrs, pair(type, id).decoder)
       rescue Plumb::ParseError => e
-        raise DecodeError, "cannot decode #{label(type, attrs[:id])}: #{e.message}"
+        raise DecodeError, "cannot decode #{label(type, id)}: #{e.message}"
       end
 
       private
 
+      # Read before the decoder runs, so it must accept both key forms the decoder does.
+      def envelope(attrs, key) = attrs.fetch(key) { attrs[key.to_s] }
+
       # --- subclass seams -------------------------------------------------------
 
       # @param klass [Class<Sourced::Message>]

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.3.0'
+    VERSION = '0.5.0'
 
     EMPTY_ARRAY = [].freeze
 
@@ -34,10 +34,24 @@ module Sourced
 
       # Accepts a UUID string or generates a new one when none is provided.
       AutoUUID = UUID::V4.default { SecureRandom.uuid }
+
+      # A JSON value, with Symbol-keyed objects at every depth. Typed all the way
+      # down so a codec decodes nested keys too. The self-references are deferred
+      # inside the union, not the constant itself: naming a type here freezes it,
+      # and a frozen Deferred can't materialize.
+      JSONValue = String | Numeric | Boolean | Nil |
+                  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)
@@ -47,7 +61,10 @@ module Sourced
     attribute? :causation_id, Types::UUID::V4
     attribute? :correlation_id, Types::UUID::V4
     attribute :created_at, LaxTime.default { Time.now }
-    attribute :metadata, Types::Hash.default(Plumb::BLANK_HASH)
+    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.
@@ -191,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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Ismael Celis
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: fugit
   requirement: !ruby/object:Gem::Requirement
@@ -74,7 +74,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Canonical typed Message class and registry shared by Sourced and Sidereal.
 test_files: []