sourced-message 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31c91f70a00fff9b43bef2a60f506086bac336a5faa52a902c405c9374afe6b5
+  data.tar.gz: 2a0923e44fe974832e726ec16d2d57b9c8e09de4351984ff92d62c8da1c4ac9f
+SHA512:
+  metadata.gz: 7877198025efae1bd7c6264da63091381dd319e5e84507fdd8f45452f3fc68298f6eafcedb005d78e75491df241c14c7364b826f81d534ecf18e9219f5661b89
+  data.tar.gz: da2f6ee90b5d568708a6a5c6b98f2fd856a6df853d35f1c9a9e482d857e7211becf8b7ef3837abaec0bf62c85f7999198977ecb14062f44f3b7bdf48affe79f2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-06
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ismael Celis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,212 @@
+# Sourced::Message
+
+`Sourced::Message` is a canonical, typed message class for event-driven Ruby systems. It is the shared base used by [Sourced](https://github.com/ismasan/sourced) and Sidereal, but it has no dependency on either and can be used on its own.
+
+A message is a [Plumb](https://github.com/ismasan/plumb)-typed value object with:
+
+- a stable, human-readable `type` string (e.g. `'course.created'`)
+- a typed, validated `payload`
+- an auto-generated `id` and `created_at` timestamp
+- `causation_id` / `correlation_id` for tracing causal chains across processes
+- arbitrary `metadata`
+- a global **type registry** that can reconstruct any message from a plain hash — handy for transports, queues and event stores
+- scheduling helpers (`#at` / `#in`) for delayed messages
+
+Messages are immutable: every "mutating" method (`#with_payload`, `#with_metadata`, `#at`, `#correlate`) returns a copy.
+
+## Installation
+
+Install the gem and add it to the application's Gemfile by executing:
+
+```bash
+bundle add sourced-message
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install sourced-message
+```
+
+Then require it:
+
+```ruby
+require 'sourced/message'
+```
+
+Requires Ruby >= 3.2.
+
+## Usage
+
+### Defining message types
+
+Use `.define` with a unique type string and an optional block describing the payload attributes (via Plumb's `attribute` DSL):
+
+```ruby
+CourseCreated = Sourced::Message.define('course.created') do
+  attribute :course_name, String
+  attribute :seats, Integer
+end
+```
+
+Each defined type is a subclass of `Sourced::Message` and is automatically added to the registry.
+
+A message can also be defined with no payload:
+
+```ruby
+PingReceived = Sourced::Message.define('ping.received')
+```
+
+### Creating messages
+
+Pass the payload as a hash. The payload is validated and coerced against the schema you declared:
+
+```ruby
+msg = CourseCreated.new(payload: { course_name: 'Ruby 101', seats: 30 })
+
+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.causation_id  # => same as msg.id by default
+msg.correlation_id # => same as msg.id by default
+```
+
+### Reading the payload
+
+The payload is a typed object. Access attributes by method, by `[]`, or with `fetch`:
+
+```ruby
+msg.payload.course_name      # => "Ruby 101"
+msg.payload[:seats]          # => 30
+msg.payload.fetch(:seats)    # => 30
+msg.payload.fetch(:missing)  # => raises KeyError
+```
+
+### Commands and events
+
+`Sourced::Command` and `Sourced::Event` are ready-made subclasses. Define types on them the same way — they register their own types, all visible from the root registry:
+
+```ruby
+EnrollStudent = Sourced::Command.define('student.enroll') do
+  attribute :student_id, String
+end
+
+StudentEnrolled = Sourced::Event.define('student.enrolled') do
+  attribute :student_id, String
+end
+```
+
+### The registry and `.from`
+
+Every defined type lives in a single registry rooted at `Sourced::Message`. This lets you reconstruct the correct subclass from a plain hash that carries a `:type` key — for example when reading messages off a queue, a database, or an HTTP request:
+
+```ruby
+hash = { type: 'course.created', payload: { course_name: 'Ruby 101', seats: 30 } }
+
+msg = Sourced::Message.from(hash)
+msg.class        # => CourseCreated
+msg.payload.course_name # => "Ruby 101"
+```
+
+Resolving from the root `Sourced::Message` finds types registered under any subclass (`Command`, `Event`, or your own):
+
+```ruby
+Sourced::Message.from(type: 'student.enroll', payload: { student_id: '42' }).class
+# => EnrollStudent
+
+Sourced::Message.from(type: 'unknown.type')
+# => raises Sourced::Message::UnknownMessageError
+```
+
+Inspect what's registered:
+
+```ruby
+Sourced::Message.registry.keys          # => ["course.created", "student.enroll", ...]
+Sourced::Message.registry.all.to_a      # => [CourseCreated, EnrollStudent, ...]
+Sourced::Message.registry['course.created'] # => CourseCreated
+```
+
+### Copying with changes
+
+Messages are immutable. Use the `#with_*` helpers to derive new copies:
+
+```ruby
+# Merge new metadata (keeps the same id)
+tagged = msg.with_metadata(channel: 'web', user_id: '42')
+tagged.metadata # => { channel: 'web', user_id: '42' }
+
+# Override payload attributes
+updated = msg.with_payload(seats: 25)
+updated.payload.seats # => 25
+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.
+
+```ruby
+trigger = EnrollStudent.new(payload: { student_id: '42' })
+result  = StudentEnrolled.new(payload: { student_id: '42' })
+
+caused = trigger.correlate(result)
+caused.causation_id   # => trigger.id
+caused.correlation_id # => trigger.correlation_id
+```
+
+This makes it possible to follow a chain of messages across process boundaries: all messages descending from the same originating message share a `correlation_id`, while `causation_id` records the direct parent.
+
+### Scheduling: delayed messages
+
+`#at` (aliased as `#in`) returns a copy with `created_at` set to a future instant. It accepts three forms:
+
+```ruby
+# An absolute Time / DateTime
+msg.at(Time.now + 3600)
+
+# An Integer number of seconds from now
+msg.in(60)
+
+# A Fugit / ISO8601 duration string
+msg.in('5m')
+msg.in('1h30m')
+msg.in('PT1H30M')
+```
+
+Scheduling a message into the past raises `Sourced::Message::PastMessageDateError`:
+
+```ruby
+msg.at(Time.now - 60) # => raises Sourced::Message::PastMessageDateError
+```
+
+Passing a string that isn't a duration (e.g. an absolute date) raises `ArgumentError`:
+
+```ruby
+msg.in('2026-12-31T10:00:00') # => raises ArgumentError
+```
+
+### Pattern matching with `case`/`when`
+
+`Sourced::Message.===` is transparent to wrappers that implement `#to_message`, so messages match correctly in `case`/`when` even when wrapped (e.g. by a positioned/persisted envelope):
+
+```ruby
+case message
+when CourseCreated  then handle_course_created(message)
+when StudentEnrolled then handle_student_enrolled(message)
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the `VERSION` constant in `lib/sourced/message.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ismasan/sourced-message.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/sourced/message.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'plumb'
+require 'fugit'
+
+module Sourced
+  # Canonical message class, shared by Sourced and Sidereal.
+  #
+  # A message has no +stream_id+ or +seq+ — it goes into a flat, globally-ordered
+  # log. Supports +causation_id+ / +correlation_id+ for tracing causal chains.
+  #
+  # Define message types via {.define}:
+  #
+  #   CourseCreated = Sourced::Message.define('course.created') do
+  #     attribute :course_name, String
+  #   end
+  #
+  # Subclasses (e.g. {Sourced::Command}, {Sourced::Event}, +Sidereal::Message+)
+  # all share one **top-level registry rooted at {Sourced::Message}**:
+  # {Registry#[]} recurses downward into subclass registries, so
+  # +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.1.0'
+
+    EMPTY_ARRAY = [].freeze
+
+    # Plumb types used to define the message attributes. Nested under the class
+    # so it never collides with the +Sourced::Types+ (sourced gem) or
+    # +Sidereal::Types+ modules.
+    module Types
+      include Plumb::Types
+
+      # Accepts a UUID string or generates a new one when none is provided.
+      AutoUUID = UUID::V4.default { SecureRandom.uuid }
+    end
+
+    # Raised by {.from} when a type string isn't registered.
+    UnknownMessageError = Class.new(ArgumentError)
+    # Raised by {#at} when a message would be scheduled in the past.
+    PastMessageDateError = Class.new(ArgumentError)
+
+    attribute :id, Types::AutoUUID
+    attribute :type, Types::String.present
+    attribute? :causation_id, Types::UUID::V4
+    attribute? :correlation_id, Types::UUID::V4
+    attribute :created_at, Types::Forms::Time.default { Time.now }
+    attribute :metadata, Types::Hash.default(Plumb::BLANK_HASH)
+    attribute :payload, Types::Static[nil]
+
+    # Lookup table mapping type strings to message subclasses.
+    class Registry
+      # @param message_class [Class] the root message class for this registry
+      def initialize(message_class)
+        @message_class = message_class
+        @lookup = {}
+      end
+
+      # @return [Array<String>] registered type strings
+      def keys = @lookup.keys
+
+      # @return [Array<Class>] direct subclasses of the root message class
+      def subclasses = message_class.subclasses
+
+      # Register a message class under a type string.
+      #
+      # @param key [String] message type string
+      # @param klass [Class] message subclass
+      def []=(key, klass)
+        @lookup[key] = klass
+      end
+
+      # Look up a message class by type string.
+      # Searches this registry first, then recurses into subclass registries.
+      #
+      # @param key [String] message type string
+      # @return [Class, nil]
+      def [](key)
+        klass = lookup[key]
+        return klass if klass
+
+        subclasses.each do |c|
+          klass = c.registry[key]
+          return klass if klass
+        end
+        nil
+      end
+
+      # All registered message classes across this registry and subclass registries.
+      #
+      # @return [Enumerator<Class>] if no block given
+      # @yield [Class] each registered message class
+      def all(&block)
+        return enum_for(:all) unless block
+
+        lookup.each_value(&block)
+        subclasses.each { |c| c.registry.all(&block) }
+      end
+
+      private
+
+      attr_reader :lookup, :message_class
+    end
+
+    # @return [Registry] the message type registry for this class
+    def self.registry
+      @registry ||= Registry.new(self)
+    end
+
+    # Base class for typed message payloads.
+    class Payload < Plumb::Types::Data
+      # @param key [Symbol] attribute name
+      # @return [Object] attribute value
+      def [](key) = attributes[key]
+
+      # @see Hash#fetch
+      def fetch(...) = to_h.fetch(...)
+    end
+
+    # Define a new message type. Registers it in the {.registry} and
+    # optionally defines a typed payload.
+    #
+    # @param type_str [String] unique message type identifier (e.g. 'course.created')
+    # @yield optional block to define payload attributes via +attribute+ DSL
+    # @return [Class] the new message subclass
+    #
+    # @example
+    #   UserJoined = Sourced::Message.define('user.joined') do
+    #     attribute :course_name, String
+    #     attribute :user_id, String
+    #   end
+    def self.define(type_str, &payload_block)
+      type_str.freeze unless type_str.frozen?
+
+      registry[type_str] = Class.new(self) do
+        def self.node_name = :data
+        define_singleton_method(:type) { type_str }
+
+        attribute :type, Types::Static[type_str]
+        if block_given?
+          payload_class = Class.new(Payload, &payload_block)
+          const_set(:Payload, payload_class)
+          attribute :payload, payload_class
+          names = payload_class._schema.to_h.keys.map(&:to_sym).freeze
+          define_singleton_method(:payload_attribute_names) { names }
+        end
+      end
+    end
+
+    # Instantiate the correct message subclass from a hash with a +:type+ key.
+    #
+    # Resolve from the root ({Sourced::Message}) to see types registered under
+    # any subclass — that's how a cross-process transport reconstructs both
+    # Sourced and Sidereal message types from one registry.
+    #
+    # @param attrs [Hash] must include +:type+ matching a registered type string
+    # @return [Message] instance of the appropriate subclass
+    # @raise [UnknownMessageError] if the type string is not registered
+    def self.from(attrs)
+      klass = registry[attrs[:type]]
+      raise UnknownMessageError, "Unknown message type: #{attrs[:type]}" unless klass
+
+      klass.new(attrs)
+    end
+
+    def initialize(attrs = {})
+      attrs = attrs.merge(payload: {}) unless attrs[:payload]
+      super(attrs)
+    end
+
+    # Identity implementation of the +to_message+ contract — see {.===} and any
+    # wrapper (e.g. +Sourced::PositionedMessage#to_message+).
+    def to_message = self
+
+    # Make +case/when+ transparent to a wrapper implementing +#to_message+.
+    # Ruby's default +Module#===+ is implemented in C and ignores +is_a?+
+    # overrides, so wrapped messages would otherwise fall through.
+    def self.===(other)
+      return true if super
+      return false unless other.respond_to?(:to_message)
+
+      unwrapped = other.to_message
+      !unwrapped.equal?(other) && super(unwrapped)
+    end
+
+    def with_metadata(meta = {})
+      return self if meta.empty?
+
+      with(metadata: metadata.merge(meta))
+    end
+
+    def with_payload(attrs = {})
+      hash = to_h
+      (hash[:payload] ||= {}).merge!(attrs)
+      self.class.new(hash)
+    end
+
+    # Return a copy with +created_at+ set to a future instant. Three
+    # accepted forms:
+    #
+    # - +Time+ / +DateTime+ / anything with +<+ — used as the absolute
+    #   target.
+    # - +Integer+ — interpreted as seconds; added to +Time.now+.
+    # - +String+ — parsed via +Fugit.parse_duration+ as a duration (e.g.
+    #   +'5m'+, +'1h30m'+, +'PT5M'+) and added to +Time.now+.
+    #
+    # Raises {PastMessageDateError} when the resolved target is
+    # before +created_at+.
+    def at(value)
+      target = case value
+               when Integer
+                 Time.now + value
+               when String
+                 parsed = Fugit.parse_duration(value) or
+                   raise ArgumentError,
+                         "Message#at: String argument must be an ISO8601 / Fugit duration " \
+                         "(e.g. '5m', 'PT1H30M'); got #{value.inspect}"
+                 parsed.add_to_time(Time.now).to_local_time
+               else
+                 value
+               end
+
+      if target < created_at
+        raise PastMessageDateError, "Message #{type} can't be delayed to a date in the past"
+      end
+
+      with(created_at: target)
+    end
+
+    alias in at
+
+    # Set causation and correlation IDs on another message, establishing
+    # a causal link from this message to +message+. Merges metadata.
+    #
+    # @param message [Message] the message to correlate
+    # @return [Message] a copy of +message+ with causation/correlation set
+    #
+    # @example
+    #   caused = source_event.correlate(SomeCommand.new(payload: { ... }))
+    #   caused.causation_id  # => source_event.id
+    #   caused.correlation_id # => source_event.correlation_id
+    def correlate(message)
+      attrs = {
+        causation_id: id,
+        correlation_id: correlation_id,
+        metadata: metadata.merge(message.metadata || Plumb::BLANK_HASH)
+      }
+      message.with(attrs)
+    end
+
+    # Returns the declared payload attribute names for this message class.
+    # Subclasses created via {.define} override this with a cached frozen array.
+    #
+    # @return [Array<Symbol>] attribute names (e.g. +[:course_name, :user_id]+)
+    def self.payload_attribute_names = EMPTY_ARRAY
+
+    private
+
+    # Hook called by Plumb after schema parsing, when +:id+ has been resolved.
+    # Defaults +causation_id+ and +correlation_id+ to the message's own +id+.
+    def prepare_attributes(attrs)
+      attrs[:correlation_id] = attrs[:id] unless attrs[:correlation_id]
+      attrs[:causation_id] = attrs[:id] unless attrs[:causation_id]
+      attrs
+    end
+  end
+
+  class Command < Message; end
+  class Event < Message; end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: sourced-message
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ismael Celis
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: plumb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.17
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.17
+- !ruby/object:Gem::Dependency
+  name: fugit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides Sourced::Message — a Plumb-typed message with a shared type
+  registry, payloads, correlation, and scheduling — used as the common base for Sourced
+  and Sidereal messages.
+email:
+- ismaelct@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/sourced/message.rb
+homepage: https://github.com/ismasan/sourced-message
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ismasan/sourced-message
+  source_code_uri: https://github.com/ismasan/sourced-message
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.8
+specification_version: 4
+summary: Canonical typed Message class and registry shared by Sourced and Sidereal.
+test_files: []