sourced-message 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89d0112d122ebad9c75fd3fa2051a3fa6c6eb4bb4e026d7b2c72144d78e6c6bf
-  data.tar.gz: bbed7cd0a57feffcff698a6e5581e8d98b2e0d4937022f7a016681f3e74d509d
+  metadata.gz: 12ddf9298bf827a4f20e9f2db6b9edababd24efa73323326e5cd5ff6bbedebc1
+  data.tar.gz: a88ab37ddb627868b20cd9a03615334a01d1f957fc3dedae25db4486623b983f
 SHA512:
-  metadata.gz: 4cd9e4f8c0e1fd7d0158aa2590e9e65319da802bbb2f64c1af685455520a2502f5428b329eb6e29ff65c13f59f8a3b8dbffba59e5cc6bef0adef0174421839b7
-  data.tar.gz: 0f8789016bc281b74976938d1598088a89b57c836dd3f944baa1298ac96aa0e95c42cb5b56289b71914e0249e912c3524747aa119a0be751b7a8fa7922dd644a
+  metadata.gz: 154e306175767857b9471c5700fe12ec3f73c17292af5c30826e2f61afa0dc217853e56950cddbf3decf8b38c38f5837e3cad76a822c6078cfd8904ef912093b
+  data.tar.gz: 0640b5e2560fa1dfd331ee8b015dde0b5195bf1ec55efaa1cb0e98cf4b3713ca8544b4bc784495cb09f08d32d12bc2dc4c60977b60df99b021bf6f71a6e63c76

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 ## [Unreleased]
 
+## [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`:
+  the type of the message at the root of a causal chain. `#correlate` now records the
+  source's `correlation_type` under `metadata[:correlation_type]` on the target, so
+  every consequence of a command carries the command's type. A message that was never
+  correlated answers with its own `type`. A target whose metadata already holds a
+  `correlation_type` keeps it, which starts a new chain.
+- `Sourced::Message::VERSION` is now `0.3.0`.
+
 ## [0.2.0]
 
 - Add `Sourced::Message::Codec`, the abstract serializer: it compiles a

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.2.2'
+    VERSION = '0.4.0'
 
     EMPTY_ARRAY = [].freeze
 
@@ -34,6 +34,15 @@ 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]
     end
 
     # Raised by {.from} when a type string isn't registered.
@@ -47,7 +56,7 @@ 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)
     attribute :payload, Types::Static[nil]
 
     # Lookup table mapping type strings to message subclasses.
@@ -231,8 +240,33 @@ module Sourced
 
     alias in at
 
+    # Metadata key under which {#correlate} records the {#correlation_type}.
+    CORRELATION_TYPE_KEY = :correlation_type
+
+    # The type of the message at the root of this message's causal chain —
+    # the type counterpart of {#correlation_id}.
+    #
+    # A message that was not produced by {#correlate} is its own root, so
+    # this is its own {#type}. A correlated message inherits its source's
+    # +correlation_type+, so every consequence of a command — the events it
+    # produced, the commands those events triggered, their events in turn —
+    # answers with the originating command's type. This is what lets a
+    # subscriber that only knows the command it sent recognise everything
+    # that came of it, without knowing the shape of each downstream message.
+    #
+    # Setting +metadata[:correlation_type]+ explicitly on a message before it
+    # is correlated starts a new chain from it: the target's own metadata wins
+    # the merge in {#correlate}.
+    #
+    # @return [String] a message type string
+    def correlation_type
+      metadata.fetch(CORRELATION_TYPE_KEY, type)
+    end
+
     # Set causation and correlation IDs on another message, establishing
-    # a causal link from this message to +message+. Merges metadata.
+    # a causal link from this message to +message+. Merges metadata, with the
+    # target's keys winning, and records this message's {#correlation_type}
+    # under {CORRELATION_TYPE_KEY} unless the target already carries one.
     #
     # @param message [Message] the message to correlate
     # @return [Message] a copy of +message+ with causation/correlation set
@@ -241,11 +275,14 @@ module Sourced
     #   caused = source_event.correlate(SomeCommand.new(payload: { ... }))
     #   caused.causation_id  # => source_event.id
     #   caused.correlation_id # => source_event.correlation_id
+    #   caused.correlation_type # => source_event.correlation_type
     def correlate(message)
       attrs = {
         causation_id: id,
         correlation_id: correlation_id,
-        metadata: metadata.merge(message.metadata || Plumb::BLANK_HASH)
+        metadata: { CORRELATION_TYPE_KEY => correlation_type }
+          .merge(metadata)
+          .merge(message.metadata || Plumb::BLANK_HASH)
       }
       message.with(attrs)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sourced-message
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.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: []