servus 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58e6098b9ea316c670b5b8aa6f61828d961cc3c8ad6e72357d71c442dfe75151
-  data.tar.gz: 215f0f790ad36575b0b9de3f956cf585f19051c16d5250ada1ae152a969dd1d7
+  metadata.gz: 7e468137fc40c9d2f18214dea55b9c3fc6211e5479e73f5b0917ed168d116a2f
+  data.tar.gz: 5390b065cb3478d837cbd90047a7f8facaaf33273b0e2aa4d459167343354d8d
 SHA512:
-  metadata.gz: 48142cd74cbd766846ccd9d8bf4a71a8d67136cbd60bdc948ddda6a0fa99f7e6072351b6ff98958500a6d84e49d1cb7d122e8e435efeb8b1384d39a4be9932ad
-  data.tar.gz: 13899ee4220e2e25b888eae9b6675a77780770628717bc11a2abda9bdd82e49b0798d70c954f91e5649a3bc281d9b3ad0e50dce41374f3c2ebc42125d7321848
+  metadata.gz: 20e5b65a0cd82207a0c494b76e21d0562ce41ca27394b418e7d6921b841c4f47d4f8384f157146195eea713f1af3d28d09b81c210fd7f8a5041b13f8464d66a2
+  data.tar.gz: 52f7ca40905dc890fa6850cf87b8394471a94607749457aaeb4784c4524315fd769e40daa4322aae12b5bd84eb9282524a90836bab8a31ab9abfe01d021211a7

data/lib/generators/servus/event_handler/event_handler_generator.rb

@@ -44,7 +44,7 @@ module Servus
       # @return [String] spec file path
       # @api private
       def handler_spec_path
-        File.join('spec', Servus.config.events_dir, "#{file_name}_handler_spec.rb")
+        File.join(Servus.config.tests_dir, Servus.config.events_dir, "#{file_name}_handler_spec.rb")
       end
 
       # Returns the handler class name.

data/lib/generators/servus/guard/guard_generator.rb

@@ -44,7 +44,7 @@ module Servus
       # @return [String] spec file path
       # @api private
       def guard_spec_path
-        File.join('spec', Servus.config.guards_dir, "#{file_name}_guard_spec.rb")
+        File.join(Servus.config.tests_dir, Servus.config.guards_dir, "#{file_name}_guard_spec.rb")
       end
 
       # Returns the guard class name.

data/lib/generators/servus/guard/templates/guard.rb.erb

@@ -34,14 +34,16 @@ class <%= guard_class_name %> < Servus::Guard
 
   # Tests whether the <%= file_name.humanize.downcase %> condition is met.
   #
-  # @param kwargs [Hash] the arguments to validate
+  # Arguments passed to `enforce_*!` / `check_*?` are stored as `@kwargs`
+  # and exposed via `method_missing`, so read them directly off the instance.
+  #
   # @return [Boolean] true if validation passes
-  def test(**kwargs)
+  def test
     # TODO: Implement validation logic
     # Return true if the condition is met, false otherwise
     #
     # Example:
-    #   def test(account:, amount:)
+    #   def test
     #     account.balance >= amount
     #   end
     true

data/lib/generators/servus/service/service_generator.rb

@@ -57,7 +57,7 @@ module Servus
       # @return [String] spec file path
       # @api private
       def service_path_spec
-        "spec/services/#{file_path}/service_spec.rb"
+        "#{Servus.config.tests_dir}/services/#{file_path}/service_spec.rb"
       end
 
       # Returns the path for the result schema file.

data/lib/servus/base.rb

@@ -48,6 +48,7 @@ module Servus
   class Base
     include Servus::Support::Errors
     include Servus::Support::Rescuer
+    include Servus::Support::Lockdown
     include Servus::Events::Emitter
     include Servus::Guards
 
@@ -157,6 +158,46 @@ module Servus
       raise type, message
     end
 
+    # Invokes another service from within this service's {#call} and returns its
+    # data on success. On failure, halts the outer service with the sub-service's
+    # failure Response — the outer service's caller receives that Response
+    # unchanged (same error object, message, code, http_status).
+    #
+    # Sugar over:
+    #
+    #   result = SubService.call(**params)
+    #   return result unless result.success?
+    #   data = result.data
+    #
+    # Only call from within a service's `#call` (or helpers reachable from
+    # it); the throw is caught by {Servus::Base.call}.
+    #
+    # @example Composing services
+    #   class SendDigitalCash::Service < Servus::Base
+    #     def call
+    #       data1 = call!(Accounts::Lookup::Service, id: account_id)
+    #       data2 = call!(Ledger::RecordTransfer::Service, account:, amount:)
+    #       success(ref: data2.ref)
+    #     end
+    #   end
+    #
+    # For invoking a service from *outside* a service context (controllers,
+    # rake tasks, jobs, consoles), see
+    # {Servus::Helpers::ControllerHelpers#run_service!}.
+    #
+    # @param service_class [Class<Servus::Base>] the sub-service to invoke
+    # @param params [Hash] keyword arguments to pass to the sub-service
+    # @return [Servus::Support::DataObject, Object] the sub-service's data on success
+    # @throw [:guard_failure, Servus::Support::Response] the failure Response, otherwise
+    #
+    # @see Servus::Helpers::ControllerHelpers#run_service!
+    def call!(service_class, **params)
+      result = service_class.call(**params)
+      return result.data if result.success?
+
+      throw(:guard_failure, result)
+    end
+
     class << self
       # Executes the service with automatic validation, logging, and benchmarking.
       #
@@ -196,11 +237,13 @@ module Servus
 
         # Wrap execution in catch block to handle guard failures
         result = catch(:guard_failure) do
-          benchmark(**args) { instance.call }
+          benchmark(**args) { instance.send(:call) }
         end
 
-        # If result is a GuardError, a guard failed - wrap in failure Response
-        result = Response.new(false, nil, result) if result.is_a?(Servus::Support::Errors::GuardError)
+        if result.is_a?(Servus::Support::Errors::GuardError)
+          Logger.log_guard_failure(self, result)
+          result = Response.new(false, nil, result)
+        end
 
         after_call(result, instance)
 

data/lib/servus/config.rb

@@ -51,22 +51,90 @@ module Servus
     # @return [String] the guards directory path
     attr_accessor :guards_dir
 
+    # The directory where generated spec/test files are placed.
+    #
+    # Defaults to `"spec"`. Projects using Minitest or a custom test layout
+    # can override this (e.g., `"test"`) so generators write files into the
+    # correct location.
+    #
+    # @return [String] the tests directory path
+    attr_accessor :tests_dir
+
     # Whether to include the default built-in guards (EnsurePresent, EnsurePositive).
     #
     # @return [Boolean] true to include default guards, false to exclude them
     attr_accessor :include_default_guards
 
+    # Whether to require all services to define an arguments schema.
+    #
+    # When enabled, raises {Servus::Support::Errors::SchemaRequiredError} when
+    # a service is called without an arguments schema defined.
+    #
+    # @return [Boolean] true to require arguments schemas, false to allow schema-less services
+    attr_accessor :require_service_arguments_schema
+
+    # Whether to require all services to define a result schema.
+    #
+    # When enabled, raises {Servus::Support::Errors::SchemaRequiredError} when
+    # a service returns a successful response without a result schema defined.
+    # Failure schemas remain optional regardless of this setting.
+    #
+    # @return [Boolean] true to require result schemas, false to allow schema-less services
+    attr_accessor :require_service_result_schema
+
+    # Whether to require all event handlers to define a payload schema.
+    #
+    # When enabled, raises {Servus::Support::Errors::SchemaRequiredError} when
+    # an event handler validates a payload without a payload schema defined.
+    #
+    # @return [Boolean] true to require payload schemas, false to allow schema-less handlers
+    attr_accessor :require_event_payload_schema
+
+    # Whether external instantiation of services is blocked and instance
+    # `#call` methods are automatically privatized.
+    #
+    # When enabled (default), callers must invoke services via the class
+    # method {Servus::Base.call}, which runs argument validation, logging,
+    # benchmarking, guards, result validation, and event emission. Calling
+    # `MyService.new` or `instance.call` directly raises `NoMethodError`.
+    #
+    # Disable this if you have existing code that instantiates services
+    # directly or otherwise prefer to opt out of the enforcement.
+    #
+    # @return [Boolean] true to enforce lockdown (default), false to allow
+    #   direct instantiation and public instance `#call`
+    # @see Servus::Support::Lockdown
+    attr_reader :lockdown_enabled
+
+    # Sets whether lockdown is enforced, immediately re-applying the
+    # resulting `.new` visibility to {Servus::Base}.
+    #
+    # @param value [Boolean] the new lockdown setting
+    # @return [Boolean] the new value
+    def lockdown_enabled=(value)
+      @lockdown_enabled = value
+      Servus::Base.apply_lockdown!
+    end
+
     # Initializes a new configuration with default values.
     #
     # @api private
     def initialize
+      set_default_directories
+      @strict_event_validation          = true
+      @include_default_guards           = true
+      @lockdown_enabled                 = true
+      @require_service_arguments_schema = false
+      @require_service_result_schema    = false
+      @require_event_payload_schema     = false
+    end
+
+    def set_default_directories
       @guards_dir   = 'app/guards'
       @events_dir   = 'app/events'
       @schemas_dir  = 'app/schemas'
       @services_dir = 'app/services'
-
-      @strict_event_validation = true
-      @include_default_guards  = true
+      @tests_dir    = 'spec'
     end
 
     # Returns the full path to a service's schema file.

data/lib/servus/events/bus.rb

@@ -91,6 +91,35 @@ module Servus
           ActiveSupport::Notifications.instrument(notification_name(event_name), payload)
         end
 
+        # Subscribes to all Servus event emissions.
+        #
+        # Yields the clean event name and payload as positional args, plus
+        # +started_at+, +finished_at+, and +id+ as keyword args.
+        # Returns the subscription for manual unsubscribe.
+        #
+        # @yield [event_name, payload, started_at:, finished_at:, id:]
+        # @yieldparam event_name [Symbol] the event name
+        # @yieldparam payload [Hash] the event payload
+        # @yieldparam started_at [Time] when the event was emitted
+        # @yieldparam finished_at [Time] when the instrumented block completed
+        # @yieldparam id [String] unique notification ID
+        # @return [Object] the ActiveSupport::Notifications subscription
+        #
+        # @example Forward all events to an external system
+        #   Servus::Events::Bus.subscribe_all do |event_name, payload, started_at:, **|
+        #     EventusForwardJob.perform_later(
+        #       event: event_name.to_s,
+        #       payload: payload.as_json,
+        #       occurred_at: started_at.utc.iso8601(6)
+        #     )
+        #   end
+        def subscribe_all(&block)
+          ActiveSupport::Notifications.subscribe(/^servus\.events\./) do |name, started, finished, id, payload|
+            event_name = name.delete_prefix('servus.events.').to_sym
+            block.call(event_name, payload, started_at: started, finished_at: finished, id: id)
+          end
+        end
+
         # Clears all registered handlers and unsubscribes from notifications.
         #
         # Useful for testing and development mode reloading.

data/lib/servus/events/emitter.rb

@@ -127,6 +127,8 @@ module Servus
       def emit_events_for(trigger, result)
         self.class.emissions_for(trigger).each do |emission|
           payload = build_event_payload(emission, result)
+          validate_event_payload!(emission[:event_name], payload)
+          Servus::Support::Logger.log_event(emission[:event_name], payload)
           Servus::Events::Bus.emit(emission[:event_name], payload)
         end
       end
@@ -134,6 +136,19 @@ module Servus
       # Instance methods for emitting events during service execution
       private
 
+      # Validates the payload against all handler schemas registered for the event.
+      #
+      # @param event_name [Symbol] the event name
+      # @param payload [Hash] the event payload
+      # @return [void]
+      # @raise [Servus::Support::Errors::ValidationError] if payload fails validation
+      # @api private
+      def validate_event_payload!(event_name, payload)
+        Servus::Events::Bus.handlers_for(event_name).each do |handler_class|
+          Servus::Support::Validator.validate_event_payload!(handler_class, payload)
+        end
+      end
+
       # Builds the event payload using the configured payload builder or defaults.
       #
       # @param emission [Hash] the emission configuration

data/lib/servus/guard.rb

@@ -19,7 +19,7 @@ module Servus
   #       }
   #     end
   #
-  #     def test(account:, amount:)
+  #     def test
   #       account.balance >= amount
   #     end
   #   end
@@ -52,7 +52,7 @@ module Servus
       #   Servus::Guard.execute!(EnsurePositive, amount: -10) # throws :guard_failure
       def execute!(guard_class, **)
         guard = guard_class.new(**)
-        return if guard.test(**)
+        return if guard.test
 
         throw(:guard_failure, guard.error)
       end
@@ -69,7 +69,7 @@ module Servus
       #   Servus::Guard.execute?(EnsurePositive, amount: 100) # => true
       #   Servus::Guard.execute?(EnsurePositive, amount: -10) # => false
       def execute?(guard_class, **)
-        guard_class.new(**).test(**)
+        guard_class.new(**).test
       end
 
       # Declares the HTTP status code for API responses.
@@ -218,14 +218,15 @@ module Servus
 
     # Tests whether the guard passes.
     #
-    # Subclasses must implement this method with explicit keyword arguments
-    # that define the guard's contract.
+    # Subclasses must implement this zero-argument method. Arguments passed
+    # to `new` are stored as `@kwargs` and exposed via `method_missing`, so
+    # `test` reads them directly off the instance.
     #
     # @return [Boolean] true if the guard passes, false otherwise
     # @raise [NotImplementedError] if not implemented by subclass
     #
     # @example
-    #   def test(account:, amount:)
+    #   def test
     #     account.balance >= amount
     #   end
     def test

data/lib/servus/guards/falsey_guard.rb

@@ -24,10 +24,10 @@ module Servus
 
       # Tests whether all specified attributes are falsey.
       #
-      # @param on [Object] the object to check
-      # @param check [Symbol, Array<Symbol>] attribute(s) to verify
+      # Reads `on` and `check` from the kwargs stored at initialization.
+      #
       # @return [Boolean] true if all attributes are falsey
-      def test(on:, check:)
+      def test
         Array(check).all? { |attr| !on.public_send(attr) }
       end
 

data/lib/servus/guards/presence_guard.rb

@@ -36,12 +36,12 @@ module Servus
       # Tests whether all provided values are present.
       #
       # A value is considered present if it is not nil and not empty
-      # (for values that respond to empty?).
+      # (for values that respond to empty?). Reads all values from the
+      # kwargs stored at initialization.
       #
-      # @param values [Hash] keyword arguments to validate
       # @return [Boolean] true if all values are present
-      def test(**values)
-        values.all? { |_, value| present?(value) }
+      def test
+        kwargs.all? { |_, value| present?(value) }
       end
 
       private

data/lib/servus/guards/state_guard.rb

@@ -24,12 +24,11 @@ module Servus
 
       # Tests whether the attribute matches the expected value(s).
       #
-      # @param on [Object] the object to check
-      # @param check [Symbol] the attribute to verify
-      # @param is [Object, Array] expected value(s) - passes if attribute matches any
+      # Reads `on`, `check`, and `is` from the kwargs stored at initialization.
+      #
       # @return [Boolean] true if attribute matches expected value(s)
-      def test(on:, check:, is:) # rubocop:disable Naming/MethodParameterName
-        Array(is).include?(on.public_send(check))
+      def test
+        Array(kwargs[:is]).include?(on.public_send(check))
       end
 
       private

data/lib/servus/guards/truthy_guard.rb

@@ -24,10 +24,10 @@ module Servus
 
       # Tests whether all specified attributes are truthy.
       #
-      # @param on [Object] the object to check
-      # @param check [Symbol, Array<Symbol>] attribute(s) to verify
+      # Reads `on` and `check` from the kwargs stored at initialization.
+      #
       # @return [Boolean] true if all attributes are truthy
-      def test(on:, check:)
+      def test
         Array(check).all? { |attr| !!on.public_send(attr) }
       end
 

data/lib/servus/helpers/controller_helpers.rb

@@ -39,6 +39,46 @@ module Servus
         render_service_error(@result.error) unless @result.success?
       end
 
+      # Executes a service and returns its data on success, raising the
+      # failure's error otherwise.
+      #
+      # The bang counterpart to {#run_service}. Use it outside a standard
+      # controller render flow — inside background logic, callbacks, or any
+      # place where a failure should propagate as an exception rather than be
+      # rendered as JSON.
+      #
+      # Inside a service's `#call` method, use {Servus::Base#call!} instead —
+      # it preserves the failure Response for the outer service's caller rather
+      # than raising.
+      #
+      # Mirrors {#run_service}: stores the full Response in @result so views
+      # and downstream helpers can reach for it the same way, then returns the
+      # data on success or raises on failure. The only behavioural difference
+      # between the two is raise-vs-render on failure.
+      #
+      # Sugar over:
+      #
+      #   @result = Service.call(**params)
+      #   raise @result.error unless @result.success?
+      #   data = @result.data
+      #
+      # @example From a rake task
+      #   data = run_service!(Treasury::Reconcile::Service, date: Date.current)
+      #
+      # @param klass [Class<Servus::Base>] service class to execute
+      # @param params [Hash] keyword arguments to pass to the service
+      # @return [Servus::Support::DataObject, Object] the service's data on success
+      # @raise [Servus::Support::Errors::ServiceError] the failure's error otherwise
+      #
+      # @see #run_service
+      # @see Servus::Base#call!
+      def run_service!(klass, **params)
+        @result = klass.call(**params)
+        return @result.data if @result.success?
+
+        raise @result.error
+      end
+
       # Renders a service error as a JSON response.
       #
       # Uses error.http_status for the response status code and

data/lib/servus/support/errors.rb

@@ -267,6 +267,22 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
+      # Raised when a service or event handler is invoked without a required schema.
+      #
+      # Triggered by the +require_service_arguments_schema+,
+      # +require_service_result_schema+, or +require_event_payload_schema+
+      # configuration flags.
+      #
+      # @see Servus::Config#require_service_arguments_schema
+      # @see Servus::Config#require_service_result_schema
+      # @see Servus::Config#require_event_payload_schema
+      class SchemaRequiredError < ServiceError
+        DEFAULT_MESSAGE = 'Schema is required but not defined'
+
+        def http_status = :unprocessable_entity
+        def api_error = { code: :schema_required, message: message }
+      end
+
       # 423 Locked - resource is locked.
       class LockedError < ServiceError
         DEFAULT_MESSAGE = 'Locked'

data/lib/servus/support/lockdown.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Servus
+  module Support
+    # Enforces that services are invoked through {Servus::Base.call} rather
+    # than by instantiating a service and calling its instance `#call`
+    # directly. The class-level `.call` runs argument validation, logging,
+    # benchmarking, guard handling, result validation, and event emission;
+    # calling the instance method directly would silently skip all of that.
+    #
+    # When included in {Servus::Base}, this module:
+    # - Privatizes `.new` on the base class (and, by inheritance, on every
+    #   descendant) so `MyService.new` from outside the class raises
+    #   `NoMethodError`.
+    # - Installs a `method_added` hook on every descendant that privatizes
+    #   any instance-level `#call` at definition time.
+    #
+    # Controlled by {Servus::Config#lockdown_enabled} (default `true`). Set
+    # it to `false` to allow direct instantiation and public instance
+    # `#call` — useful if you have existing code that relies on those entry
+    # points, or if you prefer to opt out of this enforcement entirely.
+    #
+    # @example Opting out
+    #   Servus.configure do |config|
+    #     config.lockdown_enabled = false
+    #   end
+    #
+    # @see Servus::Config#lockdown_enabled
+    module Lockdown
+      # Wires the lockdown hooks into the including class.
+      #
+      # Extends the base with {ClassMethods} (for {ClassMethods#apply_lockdown!}),
+      # prepends {Inherited} so subclasses receive the `method_added` hook,
+      # and applies the current config value to `.new`'s visibility.
+      #
+      # @param base [Class] the class including this module (expected to be {Servus::Base})
+      # @return [void]
+      # @api private
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.singleton_class.prepend(Inherited)
+        base.apply_lockdown!
+      end
+
+      # Prepended onto the base class's singleton so that every subclass of
+      # {Servus::Base} is automatically extended with {PrivateCall} at
+      # class-definition time.
+      #
+      # @api private
+      module Inherited
+        # Ensures each subclass has the `method_added` hook installed.
+        #
+        # @param subclass [Class] the newly defined subclass
+        # @return [void]
+        def inherited(subclass)
+          super
+          subclass.extend(PrivateCall)
+        end
+      end
+
+      # Extended onto every {Servus::Base} subclass. Privatizes any
+      # instance-level `#call` as soon as it is defined, provided lockdown
+      # is enabled in config at definition time.
+      #
+      # @api private
+      module PrivateCall
+        # @param name [Symbol] the name of the newly added method
+        # @return [void]
+        def method_added(name)
+          super
+          return unless Servus.config.lockdown_enabled
+
+          private :call if name == :call && public_method_defined?(:call)
+        end
+      end
+
+      # Class-level helpers installed on {Servus::Base}.
+      module ClassMethods
+        # Applies {Servus::Config#lockdown_enabled} to `.new`'s visibility.
+        # Called on include and re-called whenever the config flag changes.
+        #
+        # @return [void]
+        # @api private
+        def apply_lockdown!
+          if Servus.config.lockdown_enabled
+            singleton_class.send(:private, :new)
+          else
+            singleton_class.send(:public, :new)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servus/support/logger.rb

@@ -55,6 +55,22 @@ module Servus
         logger.warn("#{service_class.name} failed in #{duration.round(3)}s with error: #{error}")
       end
 
+      # Logs a guard failure from a service
+      #
+      # @param service_class [Class] The service class
+      # @param error [Servus::Support::Errors::GuardError] The guard error
+      def self.log_guard_failure(service_class, error)
+        logger.warn("#{service_class.name} guard failed: #{error.message}")
+      end
+
+      # Logs an event emission
+      #
+      # @param event_name [Symbol] The event name
+      # @param payload [Hash] The event payload
+      def self.log_event(event_name, payload)
+        logger.info("Event :#{event_name} emitted with payload: #{payload.inspect}")
+      end
+
       # Logs a validation error from a service
       #
       # @param service_class [Class] The service class