openhab-scripting 5.43.0 → 5.44.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b42fbceb3c29151aaef433d5992fa21dd38662e25e3644cdbdc0a81cfa392d5
-  data.tar.gz: 7ce847854bad3ccc7b2734cbd788b5a1a3fe21e82ec966240554a645a19b3518
+  metadata.gz: 14e2d94024913efabc184b537c27841fcba1136785987bd7b1423e0cde7fc072
+  data.tar.gz: c6e1746a22bba5b3e78f3f4e32dd2a5f09fdef208b098fe08558c13ff03d34e3
 SHA512:
-  metadata.gz: 8f0940e4520b47a7f35dada758fea1e079d8fca10e9e484e4d54f2cea738b7ca6d06dd81eed936c1525b5f9ef9fb884d4fb36fd4e714adc47c8d87544a824368
-  data.tar.gz: edba4793deda5989f59b0b8c106273d3ffb3963575c8dbcbeb45d75e316141cba86528c8e6126c4e53629043be86d21a6b321c174a2ec90803eec22217853634
+  metadata.gz: 41eb14f924ddfb42ea4add71eec184f0c1478b82fd129caf63bade3098e868ff78c432a7b4390ecc105b0bc22745da415b848d2f4f2b44decfffec7f8aecbf37
+  data.tar.gz: ee38fa1780d063681b6c710f4aee272ef0de6cb356a18acbe603d1e666596ffc74572d7da698084aaf6849f94b2b62396d5b4d255493b38a3ad3c9109b550af7

data/lib/openhab/core/events/abstract_event.rb

@@ -34,7 +34,20 @@ module OpenHAB
         end
 
         # @!attribute [r] source
-        # @return [String] The component that sent the event.
+        # @return [Source, nil] The component(s) that sent the event.
+        def source
+          unless instance_variable_defined?(:@source)
+            begin
+              # Disable "instance vars on non-persistent Java type"
+              original_verbose = $VERBOSE
+              $VERBOSE = nil
+              @source = get_source && Source.new(get_source)
+            ensure
+              $VERBOSE = original_verbose
+            end
+          end
+          @source
+        end
 
         #
         # Returns the event payload as a Hash.

data/lib/openhab/core/events/source.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module OpenHAB
+  module Core
+    module Events
+      #
+      # Represents the source of an event as a chain of delegated {Component Components}.
+      #
+      # This class behaves like a String representing the event source, but also provides
+      # methods to access the individual components in the delegation chain.
+      #
+      # Starting from openHAB 5.1, the source can contain multiple components
+      # that contain information about the delegation chain of the event.
+      #
+      # Each {Source::Component component} contains:
+      # - {Source::Component#bundle bundle}: The module or app.
+      #   For example: `org.openhab.automation.jrubyscripting` when a rule sends a command,
+      #   or `org.openhab.core.io.rest` when a command comes from the REST API (UI).
+      # - {Source::Component#actor actor}: Optional. The rule, user or thinguid
+      #   (e.g., "lighting_rule", "mqtt:topic:livingroom-switch:switch4")
+      #
+      # @example Log commands with source information
+      #   rule "Log item commands" do
+      #     received_command MyItem
+      #     run do |event|
+      #       logger.info "#{MyItem.name} received command #{event.command} from: #{event.source}"
+      #       logger.info "  Source components:"
+      #       event.source.components.each_with_index do |component, index|
+      #         logger.info "    #{index}: bundle=#{component.bundle}, actor=#{component.actor}"
+      #       end
+      #     end
+      #   end
+      #
+      # @example Ignore commands from specific integrations
+      #   rule "Ignore UI commands" do
+      #     received_command MyItem
+      #     run do |event|
+      #       next if event.source.sender?("org.openhab.core.io.rest")
+      #       # process the command
+      #     end
+      #   end
+      #
+      # @see https://www.openhab.org/docs/developer/utils/events.html#the-core-events
+      # @see AbstractEvent#source
+      # @see OpenHAB::DSL.profile
+      #
+      class Source < Delegator
+        # The components in the event source delegation chain.
+        # @return [Array<Component>]
+        attr_reader :components
+
+        #
+        # Construct a new {Source} object.
+        #
+        # @overload initialize(source)
+        #   @param [String] source The event source as a string.
+        #
+        # @overload initialize(components)
+        #   @param [Array<Component>] components The components in the event source delegation chain.
+        #
+        def initialize(source_or_components) # rubocop:disable Lint/MissingSuper
+          @components = if source_or_components.is_a?(Array)
+                          @source = nil
+                          source_or_components.dup
+                        else
+                          @source = -source_or_components
+                          @source.split("=>").map { |s| Component.parse(s) }
+                        end.freeze
+        end
+
+        #
+        # Construct a new {Source} by adding an additional component to the delegation chain.
+        #
+        # @param [String] bundle The bundle (module, app, etc.) of the new component to add to the chain.
+        # @param [String, nil] actor The actor (user, device, etc.) of the new component to add to the chain.
+        # @return [Source]
+        #
+        def delegate(bundle, actor = nil)
+          Source.new(components + [Component.build(bundle, actor)])
+        end
+
+        #
+        # Check if the event was sent by the specified bundle or actor.
+        #
+        # Checks if any component matches the specified bundle or actor.
+        #
+        # @overload sender?(bundle_or_actor)
+        #   @param [#===] bundle_or_actor
+        #     The bundle (module, app, etc.) or actor (user, device, etc.) to check.
+        #     If either a bundle or actor in any component in the source matches, this method returns true.
+        #   @return [true, false]
+        #
+        # @overload sender?(bundle: nil, actor: nil)
+        #   @param [#===] bundle
+        #   @param [#===] actor
+        #   @return [true, false]
+        #
+        def sender?(bundle_or_actor = nil, bundle: nil, actor: nil)
+          unless bundle_or_actor || bundle || actor
+            raise ArgumentError, "Specify one of bundle_or_actor, bundle or actor"
+          end
+
+          # rubocop:disable Style/CaseEquality
+          components.any? do |sender|
+            (bundle && bundle === sender.bundle) ||
+              (actor && actor === sender.actor) ||
+              (bundle_or_actor && bundle_or_actor === sender.bundle) ||
+              (bundle_or_actor && bundle_or_actor === sender.actor)
+          end
+          # rubocop:enable Style/CaseEquality
+        end
+
+        #
+        # @param [#===] bundle The bundle (module, app, etc.) to find the actor for.
+        # @return [String, nil] the actor (user, device, etc.) for the specified bundle, if any.
+        #
+        def actor_for(bundle)
+          components.find { |c| bundle === c.bundle }&.actor # rubocop:disable Style/CaseEquality
+        end
+
+        #
+        # Construct a new {Source} without any components from the specified bundle.
+        #
+        # This is useful if you consider events from a specific bundle as sensitive,
+        # and want to filter that component out from an untrusted sender.
+        #
+        # @overload reject(bundle)
+        #   @param [#===] bundle The bundle (module, app, etc.) to reject.
+        #   @return [Source] a new Source without any components from the specified bundle.
+        #
+        # @overload reject { |component| ... }
+        #   @yieldparam [Component] component Each component in the delegation chain.
+        #   @return [Source] a new Source without any components for which the block returns true.
+        #
+        def reject(bundle = nil, &)
+          raise ArgumentError, "Either a bundle or a block must be given" unless bundle || block_given?
+
+          Source.new(if block_given?
+                       components.reject(&)
+                     else
+                       components.reject { |c| bundle === c.bundle } # rubocop:disable Style/CaseEquality
+                     end)
+        end
+
+        # @attribute [r] source
+        #
+        # The event source as a string.
+        #
+        # @return [String]
+        #
+        def source
+          @source ||= components.join("=>").freeze
+        end
+
+        # @attribute [r] bundle
+        #
+        # The bundle (module, app, etc.) of the initial component that sent the event.
+        #
+        # @return [String, nil]
+        #
+        def bundle
+          components.first&.bundle
+        end
+
+        # @attribute [r] actor
+        #
+        # The actor (user, device, etc.) of the initial component that sent the event.
+        #
+        # @return [String, nil]
+        #
+        def actor
+          components.first&.actor
+        end
+
+        alias_method :to_s, :source
+        alias_method :to_str, :source
+        alias_method :inspect, :source
+        alias_method :__getobj__, :source
+
+        # @return [true, false]
+        def ==(other)
+          return components == other.components if other.is_a?(Source)
+          return to_s == other.to_str if other.respond_to?(:to_str)
+
+          false
+        end
+
+        # @return [true, false]
+        def !=(other)
+          !(self == other) # rubocop:disable Style/InverseMethods
+        end
+
+        # @return [Integer, nil]
+        def <=>(other)
+          return 0 if self == other
+          return nil unless other.respond_to?(:to_str)
+
+          to_s <=> other.to_str
+        end
+
+        def eql?(other)
+          other.is_a?(Source) && components == other.components
+        end
+
+        # @return [Integer]
+        def hash
+          components.hash
+        end
+
+        # Represents a single component in the event source delegation chain.
+        class Component
+          include Comparable
+
+          # The bundle (module, app, etc.) that sent the event.
+          # @return [String]
+          attr_reader :bundle
+
+          # The actor (user, device, etc.) that sent the event.
+          # @return [String]
+          attr_reader :actor
+
+          class << self
+            #
+            # Parse a {Component} from its string representation.
+            #
+            # @param [String] component The string representation of the {Component}.
+            # @return [Component]
+            #
+            def parse(component)
+              new(*component.split("$", 2))
+            end
+
+            #
+            # Build a {Component} from the specified bundle and actor.
+            #
+            # @param [String] bundle The bundle (module, app, etc.) that sent the event.
+            # @param [String, nil] actor The actor (user, device, etc.) that sent the event.
+            # @return [Component]
+            #
+            def build(bundle, actor = nil)
+              if AbstractEvent.respond_to?(:build_source)
+                # a bit round-about, but is necessary for argument validation
+                # and escaping
+                # Only present in openHAB 5.1+
+                begin
+                  parse(AbstractEvent.build_source(bundle, actor))
+                rescue java.lang.IllegalArgumentException => e
+                  raise ArgumentError, e.message
+                end
+              else
+                new(bundle, actor)
+              end
+            end
+          end
+
+          # @return [String]
+          def to_s
+            if actor
+              "#{bundle}$#{actor}"
+            else
+              bundle
+            end
+          end
+          alias_method :to_str, :to_s
+
+          # @return [true, false]
+          def ==(other)
+            return bundle == other.bundle && actor == other.actor if other.is_a?(Component)
+            return to_s == other.to_str if other.respond_to?(:to_str)
+
+            false
+          end
+
+          # @return [true, false]
+          def !=(other)
+            !(self == other) # rubocop:disable Style/InverseMethods
+          end
+
+          # @return [Integer, nil]
+          def <=>(other)
+            return 0 if self == other
+            return nil unless other.respond_to?(:to_str)
+
+            to_s <=> other.to_str
+          end
+
+          def eql?(other)
+            other.is_a?(Component) && bundle == other.bundle && actor == other.actor
+          end
+
+          # @return [Integer]
+          def hash
+            [bundle, actor].hash
+          end
+
+          private
+
+          def initialize(bundle, actor = nil)
+            @bundle = bundle
+            @actor = actor
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/core/profile_factory.rb

@@ -92,7 +92,7 @@ module OpenHAB
           params[:command] ||= nil
           params[:trigger] ||= nil
           params[:time_series] ||= nil
-          params[:source] ||= nil
+          params[:source] = (params[:source] && Core::Events::Source.new(params[:source])) || nil
 
           kwargs = {}
           @block.parameters.each do |(param_type, name)|

data/lib/openhab/dsl/version.rb

@@ -4,6 +4,6 @@ module OpenHAB
   module DSL
     # Version of openHAB helper libraries
     # @return [String]
-    VERSION = "5.43.0"
+    VERSION = "5.44.0"
   end
 end

data/lib/openhab/dsl.rb

@@ -158,7 +158,7 @@ module OpenHAB
     # @yieldparam [Core::Things::ChannelUID] channel_uid The linked channel.
     # @yieldparam [Hash] configuration The profile configuration.
     # @yieldparam [org.openhab.core.thing.profiles.ProfileContext] context The profile context.
-    # @yieldparam [String, nil] source The source of the event.
+    # @yieldparam [Core::Events::Source, nil] source The source of the event.
     #   @since openHAB 5.1
     # @yieldreturn [Boolean] Return true from the block in order to have default processing.
     # @return [void]

data/lib/openhab/rspec/mocks/persistence_service.rb

@@ -109,10 +109,6 @@ module OpenHAB
           end
         end
 
-        def get_default_strategies # rubocop:disable Naming/AccessorMethodName -- must match Java interface
-          [org.openhab.core.persistence.strategy.PersistenceStrategy::Globals::CHANGE]
-        end
-
         private
 
         def query_internal(filter, &)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.43.0
+  version: 5.44.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -96,6 +96,7 @@ files:
 - lib/openhab/core/events/item_state_event.rb
 - lib/openhab/core/events/item_state_updated_event.rb
 - lib/openhab/core/events/item_time_series_updated_event.rb
+- lib/openhab/core/events/source.rb
 - lib/openhab/core/events/startlevel_event.rb
 - lib/openhab/core/events/thing_status_info_event.rb
 - lib/openhab/core/events/timer_event.rb