yes-core 1.0.0

data/lib/yes/core/test_support/jwt_helpers.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module TestSupport
+      # Helpers for generating JWT tokens in API tests.
+      module JwtHelpers
+        # @param expires_at [Time]
+        # @param host [String, nil]
+        # @param identity_id [String, nil]
+        # @return [String]
+        def jwt_sign_in(expires_at: 1.hour.from_now, host: nil, identity_id: nil)
+          generate_spec_token(expires_at, host:, identity_id:)
+        end
+
+        # @param expires_at [Time]
+        # @param data [Hash]
+        # @return [String]
+        def generate_spec_token(expires_at, data)
+          private_key = RbNaCl::Signatures::Ed25519::SigningKey.new(
+            ENV.fetch('JWT_TOKEN_AUTH_PRIVATE_KEY')
+          )
+          JWT.encode(
+            data.merge(exp: expires_at.to_i), private_key, 'ED25519'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/test_support/subscriptions_helper.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'rspec/support/spec/in_sub_process'
+require 'rspec/support/spec/stderr_splitter'
+
+ENV['GRPC_ENABLE_FORK_SUPPORT'] = '1' if defined?(GRPC)
+
+module Yes
+  module Core
+    module TestSupport
+      # RSpec helper for asserting that PgEventstore subscriptions start correctly.
+      #
+      # @example
+      #   RSpec.describe 'Subscriptions' do
+      #     include Yes::Core::TestSupport::SubscriptionsHelper
+      #
+      #     it 'starts all subscriptions' do
+      #       assert_running_subscriptions('eventstore/subscriptions.rb', 5)
+      #     end
+      #   end
+      module SubscriptionsHelper
+        include ::RSpec::Support::InSubProcess
+
+        # Asserts that the expected number of subscriptions are running.
+        #
+        # @param subscriptions_paths [Array<String>] relative paths to subscription files
+        # @param number_of_subscriptions [Integer] expected number of running subscriptions
+        # @param root [String] root directory of subscription files
+        # @param timeout [Integer] timeout in seconds for subscriptions to start
+        # @return [void]
+        def assert_running_subscriptions(*subscriptions_paths, number_of_subscriptions, root: './lib/tasks', timeout: 5)
+          GRPC.prefork if defined?(GRPC)
+          in_sub_process do
+            GRPC.postfork_child if defined?(GRPC)
+            setup_eventstore_cli
+            require_options = subscriptions_paths.flat_map { |path| ['-r', "#{root}/#{path}"] }
+            runner = Thread.new { PgEventstore::CLI.execute(['subscriptions', 'start', *require_options]) }
+            subscriptions_count = poll_subscriptions(number_of_subscriptions, timeout)
+
+            runner.exit
+            aggregate_failures do
+              expect(subscriptions_count['count_running']).to eq(number_of_subscriptions)
+              expect(subscriptions_count['count_all']).to eq(number_of_subscriptions)
+            end
+          rescue StandardError => e
+            Rails.logger.debug e.message
+            Rails.logger.debug e.backtrace
+            raise e
+          end
+          nil
+        ensure
+          GRPC.postfork_parent if defined?(GRPC)
+        end
+
+        private
+
+        # @return [void]
+        def setup_eventstore_cli
+          require 'pg_eventstore/cli'
+          PgEventstore.logger = Logger.new($stdout)
+          PgEventstore.logger.level = :error
+          PgEventstore.connection.with { |c| c.exec('DELETE FROM subscriptions') }
+          sleep 0.5
+        end
+
+        # @param expected_count [Integer] expected number of subscriptions
+        # @param timeout [Integer] timeout in seconds
+        # @return [Hash] subscription counts
+        def poll_subscriptions(expected_count, timeout)
+          deadline = timeout.seconds.from_now
+          loop do
+            counts = PgEventstore.connection.with do |c|
+              c.exec(<<~SQL.squish)
+                select count(*) filter (where state = 'running') as count_running, count(*) as count_all
+                  from subscriptions
+              SQL
+            end.first
+            break counts if (counts['count_running'] == expected_count &&
+                             counts['count_all'] == expected_count) ||
+                            Time.current > deadline
+
+            sleep 0.1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/test_support/test_helper.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module TestSupport
+      # Utility class for configuring and cleaning up Yes::Core in tests.
+      class TestHelper
+        class << self
+          # Resets the Yes::Core configuration to a clean state.
+          # @return [void]
+          def clean_up_config
+            config = Yes::Core.configuration
+            config.aggregate_shortcuts = false
+            config.super_admin_check = ->(_auth_data) { false }
+            config.logger = nil
+            config.error_reporter = nil
+            config.payload_store_client = nil
+            config.process_commands_inline = true
+            config.command_notifier_classes = []
+            config.otl_tracer = nil
+            config.auth_adapter = nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/test_support.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'test_support/event_helpers'
+require_relative 'test_support/jwt_helpers'
+require_relative 'test_support/test_helper'

data/lib/yes/core/transaction_details.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Yes
+  module Core
+    # @api private
+    module TransactionDetailsTypes
+      # OpenTelemetry context data for distributed tracing
+      class OtlContexts < Dry::Struct
+        transform_keys(&:to_sym)
+
+        context_schema = Types::Hash.schema(
+          traceparent?: Types::String,
+          service?: Types::String
+        ).with_key_transform(&:to_sym)
+
+        timestamps_schema = Types::Hash.schema(
+          command_request_started_at_ms?: Types::Integer,
+          command_handling_started_at_ms?: Types::Integer
+        ).with_key_transform(&:to_sym)
+
+        attribute?(:root, context_schema.default { {} })
+        attribute?(:publisher, context_schema.default { {} })
+        attribute?(:timestamps, timestamps_schema.default { {} })
+
+        # @param context [Hash]
+        def publisher=(context)
+          @attributes = attributes.merge(publisher: context)
+        end
+
+        # @param context [Hash]
+        def root=(context)
+          @attributes = attributes.merge(root: context)
+        end
+      end
+    end
+
+    # Value object representing a command transaction's context.
+    #
+    # Carries correlation/causation IDs for event sourcing traceability,
+    # caller identity, and OpenTelemetry trace context.
+    #
+    # @example
+    #   TransactionDetails.new(
+    #     name: "CreateUser",
+    #     correlation_id: SecureRandom.uuid,
+    #     caller_id: current_user.id,
+    #     caller_type: 'User'
+    #   )
+    class TransactionDetails < Dry::Struct
+      schema schema.strict
+      transform_keys(&:to_sym)
+
+      attribute?(:name, Types::String.optional.default(nil))
+      attribute(:correlation_id, Types::UUID.default { SecureRandom.uuid })
+      attribute?(:causation_id, Types::UUID.optional.default(nil))
+      attribute?(:caller_id, Types::UUID.optional.default(nil))
+      attribute?(:caller_type, Types::String.optional.default(nil))
+      attribute?(:otl_contexts, TransactionDetailsTypes::OtlContexts)
+
+      # Returns metadata formatted for the event store.
+      #
+      # @return [Hash] with :$correlationId and :$causationId keys
+      def for_eventstore_metadata
+        to_h.slice(:correlation_id, :causation_id, :otl_contexts).tap do |h|
+          h[:$correlationId] = h.delete(:correlation_id)
+          h[:$causationId] = h.delete(:causation_id)
+        end
+      end
+
+      # @return [Hash] compact hash representation
+      def to_h
+        super.compact
+      end
+
+      # Creates TransactionDetails from an existing event.
+      #
+      # @param event [Yes::Core::Event] the source event
+      # @return [TransactionDetails]
+      def self.from_event(event)
+        new(
+          correlation_id: event.metadata['$correlationId'].presence || SecureRandom.uuid,
+          causation_id: event.id,
+          otl_contexts: event.metadata['otl_contexts']
+        )
+      end
+    end
+  end
+end

data/lib/yes/core/type_lookup.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class TypeLookup
+      def self.type_for(type, context, obj_type = :command)
+        new(type, context, obj_type).type_for
+      end
+
+      def initialize(type, context, obj_type)
+        @type = type
+        @context = context
+        @obj_type = obj_type
+      end
+
+      def type_for # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+        return @type if basic_event_type?
+
+        case @type
+        when :lat, :lng
+          @obj_type == :event ? :float : Yes::Core::Types::Coercible::Float
+        when :string
+          base = Yes::Core::Types::Coercible::String
+          return base if @obj_type == :event
+
+          base.prepend { |v| v.nil? ? raise(Dry::Types::CoercionError, 'nil is not a string') : v }
+        when :integer
+          Yes::Core::Types::Coercible::Integer
+        when :boolean
+          Yes::Core::Types::Strict::Bool
+        when :float
+          Yes::Core::Types::Coercible::Float
+        when :uuid
+          Yes::Core::Types::UUID
+        when :uuids
+          Yes::Core::Types::UUIDS
+        when :email
+          Yes::Core::Types::EMAIL
+        when :url
+          Yes::Core::Types::URL
+        when :optional_url
+          Yes::Core::Types::OPTIONAL_URL
+        when :hash
+          Yes::Core::Types::Hash
+        when :years
+          Yes::Core::Types::YEARS
+        when :locale
+          Yes::Core::Types::LOCALE
+        when :year
+          Yes::Core::Types::YEAR
+        when :year_date_hash
+          Yes::Core::Types::YEAR_DATE_HASH
+        when :emails
+          Yes::Core::Types::EMAILS
+        when :datetime
+          Yes::Core::Types::DATE_TIME
+        when :date_value
+          Yes::Core::Types::DateValue
+        when :period
+          Yes::Core::Types::PERIOD
+        when :dimensions
+          Yes::Core::Types::DIMENSIONS
+        when :array
+          Yes::Core::Types::Array
+        else
+          lookup_type(@type.to_s.upcase)
+        end
+      end
+
+      private
+
+      def basic_event_type?
+        [':string', ':integer', ':boolean', ':float'].include?(@type) && @obj_type == :event
+      end
+
+      def lookup_type(value)
+        return "#{@context}::Types::#{value}".constantize if Object.const_defined?("#{@context}::Types::#{value}")
+
+        return Yes::Core::Types.const_get(value) if Yes::Core::Types.const_defined?(value)
+
+        registered = Yes::Core::Types.lookup(value.downcase.to_sym)
+        return registered if registered
+
+        raise "Unknown type #{@type}"
+      end
+    end
+  end
+end

data/lib/yes/core/types.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'dry-types'
+
+module Yes
+  module Core
+    # Type definitions for the Yes event sourcing framework.
+    #
+    # Provides generic types built on Dry::Types for use in commands, events,
+    # and attribute definitions. Domain-specific types can be registered by
+    # consuming applications via {.register}.
+    #
+    # @example Registering a custom type
+    #   Yes::Core::Types.register(:team_role, Yes::Core::Types::String.enum('lead', 'member'))
+    module Types
+      include Dry.Types()
+
+      # @!group Constants
+
+      EMPTY_STRING = /\A\s*\z/
+
+      UUID_REGEXP_BASE = /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}/
+      UUID_REGEXP = /\A#{UUID_REGEXP_BASE}\z/i
+
+      DATE_TIME_REGEXP = /\A\d{4}-\d{1,2}-\d{1,2} ([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?\z/i
+
+      EMAIL_REGEXP = Regexp.union(::URI::MailTo::EMAIL_REGEXP, /^$/)
+
+      URL_REGEXP = Regexp.new("^#{URI::DEFAULT_PARSER.make_regexp(%w[https])}").freeze
+
+      # @!endgroup
+
+      # @!group Generic Types
+
+      UUID = Types::Strict::String.constrained(format: UUID_REGEXP)
+
+      ORDERED_ARRAY_ASC = ->(value) { value == value.sort }
+
+      UUIDS = Types::Array.of(UUID).constrained(case: ORDERED_ARRAY_ASC)
+
+      DATE_TIME = Types::Strict::String.constrained(format: DATE_TIME_REGEXP)
+
+      START_BEFORE_END = ->(value) { ::DateTime.parse(value[:start]) < ::DateTime.parse(value[:end]) }
+      PERIOD = Types::Hash.schema(start: DATE_TIME, end: DATE_TIME).constrained(case: START_BEFORE_END)
+
+      EMAIL = Types::Strict::String.constrained(format: EMAIL_REGEXP)
+      EMAILS = Types::Array.of(EMAIL).constrained(case: ORDERED_ARRAY_ASC)
+
+      URL = Types::Strict::String.constrained(format: URL_REGEXP)
+      OPTIONAL_URL = Types::Strict::String.constrained(format: Regexp.union(EMPTY_STRING, URL_REGEXP))
+
+      FileName = Types::String.constructor { |str| str ? str.strip.chomp : str }
+
+      DateValue = Types::String.constrained(format: /^\d{4}-\d{2}-\d{2}$/)
+
+      YEAR_FORMAT = ->(value) { value.to_s =~ /^\d{4}$/ }
+      YEAR_RANGE = ->(value) { value.to_s.to_i.between?(2000, 2050) }
+      YearAvailabilityRange = Types::Any.constrained(case: YEAR_FORMAT).constrained(case: YEAR_RANGE)
+
+      YEAR = YearAvailabilityRange
+      YEARS = Types::Array.of(YearAvailabilityRange).constrained(case: ORDERED_ARRAY_ASC)
+
+      YEAR_DATE_HASH_CONSTRAINT = lambda { |hash|
+        hash.keys.all? { |key| YearAvailabilityRange.valid?(key.to_s) } &&
+          hash.values.all? { |value| DateValue.valid?(value) }
+      }
+      PRESENT = ->(value) { value.size.positive? }
+      YEAR_DATE_HASH = Types::Hash.constrained(case: YEAR_DATE_HASH_CONSTRAINT).constrained(case: PRESENT)
+
+      LOCALE = Types::String.enum('de-CH', 'fr-CH', 'it-CH').constructor(&:to_s)
+
+      DimensionValue = Types::Coercible::Integer.constrained(gteq: 0)
+      DIMENSIONS = Types::Hash.schema(width: DimensionValue, height: DimensionValue)
+
+      PAYLOAD_STORE_TYPE = Types::String.constrained(
+        format: Regexp.new("\\Apayload-store:#{UUID_REGEXP_BASE}\\z", 'i')
+      )
+
+      # @!endgroup
+
+      class << self
+        # Registers a custom type that can be looked up by name.
+        #
+        # @param name [Symbol] the type name (e.g. :team_role)
+        # @param type [Dry::Types::Type] the type definition
+        # @return [void]
+        # @example
+        #   Yes::Core::Types.register(:subscription_type, Yes::Core::Types::String.enum('premium', 'basic'))
+        def register(name, type)
+          custom_types[name] = type
+          const_set(name.to_s.upcase, type) unless const_defined?(name.to_s.upcase)
+        end
+
+        # Looks up a registered custom type by name.
+        #
+        # @param name [Symbol] the type name
+        # @return [Dry::Types::Type, nil] the type or nil if not found
+        def lookup(name)
+          custom_types[name]
+        end
+
+        # @return [Hash{Symbol => Dry::Types::Type}] all registered custom types
+        def custom_types
+          @custom_types ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/utils/aggregate_shortcuts.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Utils
+      # Provides convenient shortcuts for accessing aggregate classes in Rails console
+      # @example
+      #   # Instead of: ApprenticeshipPresentation::Apprenticeship::Aggregate.new(id)
+      #   # Use: AP::Appr.new(id)
+      class AggregateShortcuts
+        class << self
+          # Load aggregate shortcuts in Rails console
+          # Creates module aliases and constants for convenient access
+          def load!
+            return unless Yes::Core.configuration.aggregate_shortcuts
+
+            load_overrides
+            discover_aggregates
+            create_shortcuts
+            define_helper_method
+          end
+
+          # List all available shortcuts
+          # @param filter [String, nil] Optional filter to show only specific context
+          # @return [Hash] Hash of shortcuts and their full paths
+          # @example
+          #   AggregateShortcuts.list
+          #   AggregateShortcuts.list('AP')
+          def list(filter = nil)
+            results = @shortcuts || {}
+            results = results.select { |shortcut, _| shortcut.start_with?("#{filter}::") } if filter
+            results
+          end
+
+          # Display shortcuts in a formatted table
+          # @param filter [String, nil] Optional filter
+          def display(filter = nil)
+            shortcuts = list(filter)
+
+            if shortcuts.empty?
+              Rails.logger.debug { "No shortcuts found#{" for '#{filter}'" if filter}." }
+              return
+            end
+
+            max_shortcut_length = shortcuts.keys.map(&:length).max
+
+            Rails.logger.debug "\nAvailable Aggregate Shortcuts:"
+            Rails.logger.debug '=' * (max_shortcut_length + 70)
+            shortcuts.sort.each do |shortcut, full_path|
+              Rails.logger.debug "#{shortcut.ljust(max_shortcut_length)} → #{full_path}"
+            end
+            Rails.logger.debug '=' * (max_shortcut_length + 70)
+            Rails.logger.debug { "\nUsage: #{shortcuts.keys.first}.new(id)" } if shortcuts.any?
+          end
+
+          private
+
+          def load_overrides
+            @context_overrides = {}
+            @subject_overrides = {}
+
+            config_path = Rails.root.join('config/aggregate_shortcuts.yml')
+            return unless File.exist?(config_path)
+
+            config = YAML.load_file(config_path)
+            @context_overrides = config['contexts'] || {}
+            @subject_overrides = config['subjects'] || {}
+          rescue StandardError => e
+            Rails.logger.warn("Failed to load aggregate shortcuts config: #{e.message}")
+          end
+
+          def discover_aggregates
+            @aggregates = []
+
+            Rails.root.glob('app/contexts/**/aggregate.rb').each do |file|
+              require file
+              parts = file.to_s.split('contexts/').last.split('/')
+              context = parts[0]
+              subject = parts[1]
+
+              class_name = "#{context.camelize}::#{subject.camelize}::Aggregate"
+              klass = class_name.constantize
+
+              next unless klass < Yes::Core::Aggregate
+
+              @aggregates << {
+                context: context.camelize,
+                subject: subject.camelize,
+                class: klass,
+                class_name: class_name
+              }
+            rescue NameError, LoadError => e
+              Rails.logger.debug { "Skipping #{file}: #{e.message}" }
+            end
+          end
+
+          def create_shortcuts
+            @shortcuts = {}
+            context_modules = {}
+
+            @aggregates.each do |agg|
+              context_abbr = abbreviate_context(agg[:context])
+              subject_abbr = abbreviate_subject(agg[:subject])
+
+              # Create context module alias if not exists
+              unless context_modules[context_abbr]
+                if Object.const_defined?(context_abbr)
+                  Rails.logger.warn("Shortcut conflict: #{context_abbr} already defined, skipping #{agg[:context]}")
+                  next
+                end
+
+                context_module = agg[:context].constantize
+                Object.const_set(context_abbr, context_module)
+                context_modules[context_abbr] = context_module
+              end
+
+              # Create subject constant within context module
+              context_mod = context_modules[context_abbr]
+              if context_mod.const_defined?(subject_abbr)
+                Rails.logger.warn("Shortcut conflict: #{context_abbr}::#{subject_abbr} already defined")
+                next
+              end
+
+              context_mod.const_set(subject_abbr, agg[:class])
+
+              shortcut_name = "#{context_abbr}::#{subject_abbr}"
+              @shortcuts[shortcut_name] = agg[:class_name]
+            end
+          end
+
+          def abbreviate_context(context)
+            return @context_overrides[context] if @context_overrides[context]
+
+            # Extract capital letters from CamelCase
+            # ApprenticeshipPresentation → AP
+            # CompanyManagement → CM
+            context.scan(/[A-Z]/).join
+          end
+
+          def abbreviate_subject(subject)
+            return @subject_overrides[subject] if @subject_overrides[subject]
+
+            # First try capital letters
+            capitals = subject.scan(/[A-Z]/).join
+            return capitals if capitals.length > 1
+
+            # Otherwise use first 4 characters
+            subject[0..3]
+          end
+
+          def define_helper_method
+            # Define global helper method for console
+            Object.class_eval do
+              define_method(:shortcuts) do |filter = nil|
+                Yes::Core::Utils::AggregateShortcuts.display(filter)
+                nil # Don't return anything to avoid console clutter
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/utils/caller_utils.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Utils
+      # Utility module for handling caller-related operations
+      module CallerUtils
+        class << self
+          # Extracts a formatted origin string from a caller location
+          # @param caller [Thread::Backtrace::Location] caller location
+          # @return [String] origin of the command, derived from caller
+          def origin_from_caller(caller)
+            root_path = defined?(Rails) ? Rails.root.to_s : ''
+            # #absolute_path may be nil in case the code is run under irb for example. In this case - grab the script
+            # name by calling #path
+            caller_path = caller.absolute_path || caller.path
+            caller_path.
+              sub("#{root_path}/", '').
+              sub('.rb', '').
+              split('/').
+              map { |s| s.split('_').map(&:capitalize).join }.
+              join(' > ')
+          end
+
+          # Returns an origin string identifying the Rails console context, or nil if not in a console
+          # @return [String, nil] origin string like "CompanyManager production console"
+          def console_origin
+            return unless defined?(Rails::Console)
+
+            app_name = Rails.application.class.module_parent.name
+            "#{app_name} #{Rails.env} console"
+          end
+        end
+      end
+    end
+  end
+end