servus 0.7.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0560049029e2b803e64323461fb8d5c8b56cdc1d69c5b5de83ca0e6a1858a65c'
-  data.tar.gz: 0d1e6a460fbbf1b5c7c26811ee8fbb5eccccf151f2c4d8d94a8270c1f1d5ef41
+  metadata.gz: bc5b23e5aa35d4127cfb7afe7e784dced5eca17c776f3561a1c00037b7b59e74
+  data.tar.gz: b70c8e9b14cd59b2e4d1eb38a0846f3cdbbabf65d372204690a4458b5d14f8af
 SHA512:
-  metadata.gz: f59299fe30eb202c0a71858dc2c1491a29f4dd5a330e65ec471b412a1e060329bfca5c51eea2d7759fbddebbb2747fd65ccb79ecd048fc4d2dc07faba3f92420
-  data.tar.gz: 81f9a1277db2e3d6b4d383c29a4be4f9c4cf92ba1bac10f680e687ea6cf4438067ec4b2b19d05ccd3909962e87e7eec738721a28cf1b65f281548bec7fbcb42e
+  metadata.gz: 6990920d0e7f5b6c9285ce9636a5fef5b301a329f05ee03316c17b4e268e7838cb83e0dd2d352e147e6865e2d5a58cc274940bb2110e52d8cdec3af3d7509f1b
+  data.tar.gz: 5b90d1643831c078ad81ad09ff04aa9baa9b84a5203f22c31e91d5cb42aa869b2e2ca089664effaab2f1c78b1d7a504840e2add6236e2b10478b44cd2bc9c17d

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

@@ -11,23 +11,26 @@
 #   <%= event_class_name %>.emit({ user_id: 123 })
 #
 # @example Invoke a service when this event fires
-#   invoke SendEmail::Service, async: true do |payload|
+#   enqueue SendEmail::Service do |payload|
 #     { user_id: payload[:user_id] }
 #   end
 #
 # @example Pass full payload through (no mapper block)
-#   invoke AuditLogger::Service, async: true
+#   enqueue AuditLogger::Service
 #
-# @example Conditional invocation
-#   invoke GrantRewards::Service, if: ->(payload) { payload[:premium] } do |payload|
+# @example Conditional
+#   enqueue GrantRewards::Service, if: ->(payload) { payload[:premium] } do |payload|
 #     { user_id: payload[:user_id] }
 #   end
 #
-# Available options for `invoke`:
-# - async: true            - Invoke service asynchronously via ActiveJob
-# - queue: :queue_name     - Specify ActiveJob queue (requires async: true)
-# - if: ->(payload) {}     - Condition that must be true to invoke
-# - unless: ->(payload) {} - Condition that must be false to invoke
+# Services are always enqueued via ActiveJob, never run inline.
+#
+# Available options for `enqueue`:
+# - queue: :queue_name     - Route the job to a queue
+# - wait: 5.minutes        - Delay before the job runs
+# - priority: 10           - Job priority (adapter-dependent)
+# - if: ->(payload) {}     - Condition that must be true to enqueue
+# - unless: ->(payload) {} - Condition that must be false to enqueue
 #
 # @see Servus::Event
 # @see Servus::Events::Bus
@@ -38,7 +41,7 @@ class <%= event_class_name %> < Servus::Event
     description: '<%= event_class_name %> event payload',
   }
 
-  # invoke YourService, async: true do |payload|
+  # enqueue YourService do |payload|
   #   { example_arg: payload[:example_field] }
   # end
 end

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

@@ -7,7 +7,6 @@ module Servus
     # Generates a complete service structure including:
     # - Service class file
     # - RSpec test file
-    # - JSON schema files for arguments and results
     #
     # @example Generate a service
     #   rails g servus:service namespace/do_something_helpful user amount
@@ -15,8 +14,6 @@ module Servus
     # @example Generated files
     #   app/services/namespace/do_something_helpful/service.rb
     #   spec/services/namespace/do_something_helpful/service_spec.rb
-    #   app/schemas/services/namespace/do_something_helpful/arguments.json
-    #   app/schemas/services/namespace/do_something_helpful/result.json
     #
     # @see https://guides.rubyonrails.org/generators.html
     class ServiceGenerator < Rails::Generators::NamedBase
@@ -30,16 +27,15 @@ module Servus
 
       # Creates all service-related files.
       #
-      # Generates the service class, spec file, and schema files from templates.
+      # Generates the service class and spec file from templates.
+      #
+      # Schemas are declared inline with the +schema+ DSL, so there are no
+      # schema files to generate — the service template scaffolds them in place.
       #
       # @return [void]
       def create_service_file
         template 'service.rb.erb', service_path
         template 'service_spec.rb.erb', service_path_spec
-
-        # Template json schemas
-        template 'result.json.erb', service_result_schema_path
-        template 'arguments.json.erb', service_arguments_shecma_path
       end
 
       private
@@ -49,7 +45,7 @@ module Servus
       # @return [String] service file path
       # @api private
       def service_path
-        "app/services/#{file_path}/service.rb"
+        File.join(Servus.config.services_dir, file_path, 'service.rb')
       end
 
       # Returns the path for the service spec file.
@@ -60,22 +56,6 @@ module Servus
         "#{Servus.config.tests_dir}/services/#{file_path}/service_spec.rb"
       end
 
-      # Returns the path for the result schema file.
-      #
-      # @return [String] result schema path
-      # @api private
-      def service_result_schema_path
-        "app/schemas/services/#{file_path}/result.json"
-      end
-
-      # Returns the path for the arguments schema file.
-      #
-      # @return [String] arguments schema path
-      # @api private
-      def service_arguments_shecma_path
-        "app/schemas/services/#{file_path}/arguments.json"
-      end
-
       # Returns the service class name with ::Service appended.
       #
       # @return [String] service class name
@@ -108,10 +88,10 @@ module Servus
       #
       # @return [String] multi-line instance variable assignments
       # @example
-      #   initialize_params # => "@user = user\n    @amount = amount"
+      #   initialize_params # => "@user = user\n      @amount = amount"
       # @api private
       def initialize_params
-        parameters.map { |param| "@#{param} = #{param}" }.join("\n    ")
+        parameters.map { |param| "@#{param} = #{param}" }.join("\n      ")
       end
 
       # Generates attr_reader declarations for parameters.

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

@@ -41,34 +41,27 @@
 module <%= class_name %>
   class Service < Servus::Base
 <%- unless options[:no_docs] -%>
-    # TODO: Define argument validation schema (optional but recommended)
-    # schema arguments: {
-    #   type: 'object',
-<%- if parameters.any? -%>
-    #   required: [<%= parameters.map { |p| "'#{p}'" }.join(', ') %>],
-<%- else -%>
-    #   required: [],
+    # TODO: give each property a type. An empty property schema accepts anything,
+    # so until these are filled in only presence is enforced.
+    # Shared shapes can be referenced instead: { '$ref' => '#/core/$defs/amount' }
 <%- end -%>
-    #   properties: {
+    schema(
+      arguments: {
+        type: 'object',
+        required: <%= parameters.empty? ? '[]' : "%w[#{parameters.join(' ')}]" %>,
+        properties: {
 <%- parameters.each do |param| -%>
-    #     <%= param %>: { type: 'string' }<%= param == parameters.last ? '' : ',' %>
+          <%= param %>: {}<%= param == parameters.last ? '' : ',' %>
 <%- end -%>
-<%- if parameters.empty? -%>
-    #     # property_name: { type: 'string' }
-<%- end -%>
-    #   }
-    # }
+        }
+      },
+      result: {
+        type: 'object',
+        required: [],
+        properties: {}
+      }
+    )
 
-    # TODO: Define result validation schema (optional)
-    # schema result: {
-    #   type: 'object',
-    #   required: [],
-    #   properties: {
-    #     # result_field: { type: 'string' }
-    #   }
-    # }
-
-<%- end -%>
 <%- unless options[:no_docs] -%>
     # Initializes the service with required parameters.
     #

data/lib/servus/base.rb

@@ -52,6 +52,63 @@ module Servus
     include Servus::Events::Emitter
     include Servus::Guards
 
+    extend Servus::Schema::Declaration
+
+    # @!method self.schema(arguments: nil, result: nil, failure: nil)
+    #   Declares the JSON schemas used to validate this service.
+    #
+    #   Arguments are validated before +call+ runs, so the body can trust the
+    #   shape of its inputs. Result data is validated after it returns, so a
+    #   service that stops honouring its own contract fails loudly rather than
+    #   shipping the wrong shape to its callers.
+    #
+    #   Schemas may reference shared fragments registered with
+    #   {Servus::Schema.register}; refs are resolved on first read.
+    #
+    #   Omitting a keyword leaves any schema declared earlier — or by a
+    #   superclass — in place. Passing one explicitly as +nil+ raises.
+    #
+    #   @param arguments [Hash] JSON schema for the service's arguments
+    #   @param result [Hash] JSON schema for successful result data
+    #   @param failure [Hash] JSON schema for failure response data
+    #   @return [void]
+    #   @raise [ArgumentError] on an unknown keyword or an explicit nil
+    #
+    #   @example Declaring arguments and result schemas
+    #     class ProcessPayment::Service < Servus::Base
+    #       schema(
+    #         arguments: {
+    #           type: 'object',
+    #           required: ['user_id', 'amount'],
+    #           properties: {
+    #             user_id: { type: 'integer' },
+    #             amount: { type: 'number', minimum: 0.01 }
+    #           }
+    #         },
+    #         result: {
+    #           type: 'object',
+    #           required: ['transaction_id'],
+    #           properties: { transaction_id: { type: 'string' } }
+    #         }
+    #       )
+    #     end
+    #
+    #   @example Referencing a shared fragment
+    #     schema arguments: {
+    #       type: 'object',
+    #       properties: { amount: { '$ref' => '#/core/$defs/amount' } }
+    #     }
+    #
+    #   @see Servus::Schema
+    #
+    # @!method self.arguments_schema
+    #   @return [Hash, nil] the compiled arguments schema
+    # @!method self.result_schema
+    #   @return [Hash, nil] the compiled result schema
+    # @!method self.failure_schema
+    #   @return [Hash, nil] the compiled failure schema
+    declare_schemas :arguments, :result, :failure
+
     # Support class aliases
     Logger = Servus::Support::Logger
     Emitter = Servus::Events::Emitter
@@ -158,46 +215,6 @@ 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.
       #
@@ -257,69 +274,6 @@ module Servus
       end
       # rubocop:enable Metrics/MethodLength
 
-      # Defines schema validation rules for the service's arguments, result, and/or failure data.
-      #
-      # This method provides a clean DSL for specifying JSON schemas that will be used
-      # to validate service inputs and outputs. Schemas defined via this method take
-      # precedence over ARGUMENTS_SCHEMA, RESULT_SCHEMA, and FAILURE_SCHEMA constants.
-      # The next major version will deprecate those constants in favor of this DSL.
-      #
-      # @param arguments [Hash, nil] JSON schema for validating service arguments
-      # @param result [Hash, nil] JSON schema for validating service result data
-      # @param failure [Hash, nil] JSON schema for validating failure response data
-      # @return [void]
-      #
-      # @example Defining both arguments and result schemas
-      #   class ProcessPayment::Service < Servus::Base
-      #     schema(
-      #       arguments: {
-      #         type: 'object',
-      #         required: ['user_id', 'amount'],
-      #         properties: {
-      #           user_id: { type: 'integer' },
-      #           amount: { type: 'number', minimum: 0.01 }
-      #         }
-      #       },
-      #       result: {
-      #         type: 'object',
-      #         required: ['transaction_id'],
-      #         properties: {
-      #           transaction_id: { type: 'string' }
-      #         }
-      #       }
-      #     )
-      #   end
-      #
-      # @example Defining only arguments schema
-      #   class SendEmail::Service < Servus::Base
-      #     schema arguments: { type: 'object', required: ['email', 'subject'] }
-      #   end
-      #
-      # @see Servus::Support::Validator
-      def schema(arguments: nil, result: nil, failure: nil)
-        @arguments_schema = arguments.with_indifferent_access if arguments
-        @result_schema    = result.with_indifferent_access    if result
-        @failure_schema   = failure.with_indifferent_access   if failure
-      end
-
-      # Returns the arguments schema defined via the schema DSL method.
-      #
-      # @return [Hash, nil] the arguments schema or nil if not defined
-      # @api private
-      attr_reader :arguments_schema
-
-      # Returns the result schema defined via the schema DSL method.
-      #
-      # @return [Hash, nil] the result schema or nil if not defined
-      # @api private
-      attr_reader :result_schema
-
-      # Returns the failure schema defined via the schema DSL method.
-      #
-      # @return [Hash, nil] the failure schema or nil if not defined
-      # @api private
-      attr_reader :failure_schema
-
       # Executes pre-call hooks including logging and argument validation.
       #
       # This method is automatically called before service execution and handles:

data/lib/servus/config.rb

@@ -4,24 +4,18 @@
 module Servus
   # Configuration settings for the Servus gem.
   #
-  # Manages global configuration options including schema file locations.
-  # Access the configuration via {Servus.config} or modify via {Servus.configure}.
+  # Manages global configuration options for services, events, guards, and
+  # logging. Access the configuration via {Servus.config} or
+  # modify via {Servus.configure}.
   #
-  # @example Customizing schema location
+  # @example Configuring Servus
   #   Servus.configure do |config|
-  #     config.schema_root = Rails.root.join('lib/schemas')
+  #     config.require_service_arguments_schema = true
   #   end
   #
   # @see Servus.config
   # @see Servus.configure
   class Config
-    # The directory where JSON schema files are located.
-    #
-    # Defaults to `Rails.root/app/schemas/services` in Rails applications.
-    #
-    # @return [String] the schemas directory path
-    attr_accessor :schemas_dir
-
     # The directory where Event classes are located.
     #
     # Defaults to `Rails.root/app/events` in Rails applications.
@@ -171,49 +165,9 @@ module Servus
     def set_default_directories
       @guards_dir   = 'app/guards'
       @events_dir   = 'app/events'
-      @schemas_dir  = 'app/schemas'
       @services_dir = 'app/services'
       @tests_dir    = 'spec'
     end
-
-    # Returns the full path to a service's schema file.
-    #
-    # @param service_namespace [String] underscored service namespace (e.g., "process_payment")
-    # @param type [String] schema type ("arguments" or "result")
-    # @return [String] full path to the schema JSON file
-    #
-    # @example
-    #   config.schema_path_for("process_payment", "arguments")
-    #   # => "/full/path/app/schemas/process_payment/arguments.json"
-    def schema_path_for(service_namespace, type)
-      File.join(root_path, schemas_dir, service_namespace, "#{type}.json")
-    end
-
-    # Returns the directory containing a service's schema files.
-    #
-    # @param service_namespace [String] underscored service namespace
-    # @return [String] directory path for the service's schemas
-    #
-    # @example
-    #   config.schema_dir_for("process_payment")
-    #   # => "/full/path/app/schemas/process_payment"
-    def schema_dir_for(service_namespace)
-      File.join(root_path, schemas_dir, service_namespace)
-    end
-
-    private
-
-    # Determines the application root path.
-    #
-    # @return [String] Rails.root in Rails apps, or gem's root directory otherwise
-    # @api private
-    def root_path
-      if defined?(Rails) && Rails.respond_to?(:root)
-        Rails.root
-      else
-        File.expand_path('../../..', __dir__)
-      end
-    end
   end
 
   # Returns the singleton configuration instance.
@@ -221,8 +175,8 @@ module Servus
   # @return [Servus::Config] the global configuration object
   #
   # @example
-  #   Servus.config.schema_root
-  #   # => "/app/app/schemas/services"
+  #   Servus.config.services_dir
+  #   # => "app/services"
   def self.config
     @config ||= Config.new
   end
@@ -234,7 +188,7 @@ module Servus
   #
   # @example
   #   Servus.configure do |config|
-  #     config.schema_root = Rails.root.join('custom/schemas')
+  #     config.require_service_result_schema = true
   #   end
   def self.configure
     yield(config)