servus 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 36f4d4b15ff9038d9c039f6efb0fe5027c6326811334dc3e478a906b31286d5d
+  data.tar.gz: 786b002fe1937d5204088fdb982156bc1fb1ce7bc1c20f2ecd4c737e23e1acd5
+SHA512:
+  metadata.gz: 04ce3e7a6cdd2371c4da93d98123ea640736856638dfa5c2a60d3c4b4c7ae1109bd597bf577cec892461677a906e0955ee782c20532901b3808eca80c6ccbb6a
+  data.tar.gz: 9c07175986bd05753df2b29dbc70f854cbab12745183d6e8937cc89dd46e5e819df588ac0ef88ea2db8298cb6e470e798a8e3361cc8765194ddee1244c7a2d1c

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-04-28
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Sebastian Scholl
+
+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,379 @@
+## Servus Gem
+
+Servus is a gem for creating and managing service objects. It includes:
+
+- A base class for service objects
+- Generators for core service objects and specs
+- Support for schema validation
+- Support for error handling
+- Support for logging
+
+
+
+## Generators
+
+Service objects can be easily created using the `rails g servus:service namespace/service_name [*params]` command. For sake of consistency, use this command when generating new service objects.
+
+### Generate Service
+
+```bash
+$ rails g servus:service namespace/do_something_helpful user
+=>    create  app/services/namespace/do_something_helpful/service.rb
+      create  spec/services/namespace/do_something_helpful/service_spec.rb
+      create  app/schemas/services/namespace/do_something_helpful/result.json
+      create  app/schemas/services/namespace/do_something_helpful/arguments.json
+```
+
+### Destroy Service
+
+```bash
+$ rails d servus:service namespace/do_something_helpful
+=>    remove  app/services/namespace/do_something_helpful/service.rb
+      remove  spec/services/namespace/do_something_helpful/service_spec.rb
+      remove  app/schemas/services/namespace/do_something_helpful/result.json
+      remove  app/schemas/services/namespace/do_something_helpful/arguments.json
+```
+
+## Arguments
+
+Service objects should use keyword arguments rather than positional arguments for improved clarity and more meaningful error messages.
+
+```ruby
+# Good ✅
+class Services::ProcessPayment::Service < Servus::Base
+  def initialize(user:, amount:, payment_method:)
+    @user = user
+    @amount = amount
+    @payment_method = payment_method
+  end
+end
+
+# Bad ❌
+class Services::ProcessPayment::Service < Servus::Base
+  def initialize(user, amount, payment_method)
+    @user = user
+    @amount = amount
+    @payment_method = payment_method
+  end
+end
+```
+
+## Directory Structure
+
+Each service belongs in its own namespace with this structure:
+
+- `app/services/service_name/service.rb` - Main class/entry point
+- `app/services/service_name/support/` - Service-specific supporting classes
+
+Supporting classes should never be used outside their parent service.
+
+```
+app/services/
+├── process_payment/
+│   ├── service.rb
+│   └── support/
+│       ├── payment_validator.rb
+│       └── receipt_generator.rb
+├── generate_report/
+│   ├── service.rb
+│   └── support/
+│       ├── report_formatter.rb
+│       └── data_collector.rb
+```
+
+## **Methods**
+
+Every service object must implement:
+
+- An `initialize` method that sets instance variables
+- A parameter-less `call` instance method that executes the service logic
+
+```ruby
+class Services::GenerateReport::Service < Servus::Base
+  def initialize(user:, report_type:, date_range:)
+    @user = user
+    @report_type = report_type
+    @date_range = date_range
+  end
+
+  def call
+    data = collect_data
+    if data.empty?
+      return failure("No data available for the selected date range")
+    end
+
+    formatted_report = format_report(data)
+    success(formatted_report)
+  end
+
+  private
+
+  def collect_data
+		# Implementation details...
+	end
+
+  def format_report(data)
+		# Implementation details...
+	end
+end
+
+```
+
+## **Inheritance**
+
+- Every main service class (`service.rb`) must inherit from `Servus::Base`
+- Supporting classes should NOT inherit from `Servus::Base`
+
+```ruby
+# Good ✅
+class Services::NotifyUser::Service < Servus::Base
+	# Service implementation
+end
+
+class Services::NotifyUser::Support::MessageBuilder
+	# Support class implementation (does NOT inherit from BaseService)
+end
+
+# Bad ❌
+class Services::NotifyUser::Support::MessageBuilder < Servus::Base
+	# Incorrect: support classes should not inherit from Base class
+end
+```
+
+## **Call Chain**
+
+Always use the class method `call` instead of manual instantiation. The `call` method:
+
+1. Initializes an instance of the service using provided keyword arguments
+2. Calls the instance-level `call` method
+3. Handles schema validation of inputs and outputs
+4. Handles logging of inputs and results
+
+```ruby
+# Good ✅
+result = Services::ProcessPayment::Service.call(
+  amount: 50,
+  user_id: 123,
+  payment_method: "credit_card"
+)
+
+# Bad ❌ - bypasses logging and other class-level functionality
+service = Services::ProcessPayment::Service.new(
+  amount: 50,
+  user_id: 123,
+  payment_method: "credit_card"
+)
+result = service.call
+
+```
+
+When services call other services, always use the class-level `call` method:
+
+```ruby
+def process_order
+# Good ✅
+  payment_result = Services::ProcessPayment::Service.call(
+    amount: @order.total,
+    payment_method: @payment_details
+  )
+
+# Bad ❌
+  payment_service = Services::ProcessPayment::Service.new(
+    amount: @order.total,
+    payment_method: @payment_details
+  )
+  payment_result = payment_service.call
+end
+
+```
+
+## **Responses**
+
+The `Servus::Base` provides standardized response methods:
+
+- `success(data)` - Returns success with data as a single argument
+- `failure(message, **options)` - Logs error and returns failure response
+- `error!(message)` - Logs error and raises exception
+
+```ruby
+def call
+	# Return failure with message
+	return failure("Order is not in a pending state") unless @order.pending?
+
+    # Do something important
+
+	# Process and return success with single data object
+    success({
+        order_id: @order.id,
+        status: "processed",
+        timestamp: Time.now
+    })
+end
+```
+
+All responses are `Servus::Support::Response` objects with a `success?` boolean attribute and either `data` (for success) or `error` (for error) attributes.
+
+### Service Error Returns and Handling
+
+By default, the `failure(...)` method creates an instance of `ServiceError` and adds it to the response type's `error` attribute. Standard and custom error types should inherit from the `ServiceError` class and optionally implement a custom `api_error` method. This enables developers to choose between using an API-specific error or generic error message in the calling context.
+
+```ruby
+# Called from within a Service Object
+class SomeServiceObject::Service < Servus::Base
+	def call
+		# Return default ServiceError with custom message
+		failure("That didn't work for some reason")
+		#=> Response(false, nil, ApplicationService::Support::Errors::ServiceError("That didn't work for some reason"))
+		#
+		# OR
+		#
+		# Specify ServiceError type with custom message
+		failure("Custom message", type: Servus::Support::Errors::NotFoundError)
+		#=> Response(false, nil, ApplicationService::Support::Errors::NotFoundError("Custom message"))
+		#
+		# OR
+		#
+		# Specify ServiceError type with default message
+		failure(type: Servus::Support::Errors::NotFoundError)
+		#=> Response(false, nil, ApplicationService::Support::Errors::NotFoundError("Record not found"))
+		#
+		# OR
+		#
+		# Accept all defaults
+		failure
+		#=> Response(false, nil, ApplicationService::Support::Errors::ServiceError("An error occurred"))
+	end
+end
+
+# Error handling in parent context
+class SomeController < AppController
+	def controller_action
+	  result = SomeServiceObject::Service.call(arg: 1)
+	
+	  return if result.success?
+	
+	  # If you just want the error message
+	  bad_request(result.error.message)
+	
+	  # If you want the API error
+	  service_object_error(result.error.api_error)
+	end
+end
+```
+
+## **Schema Validation**
+
+Service objects support two methods for schema validation: JSON Schema files and inline schema declarations.
+
+### 1. File-based Schema Validation
+
+Every service can have corresponding schema files in the centralized schema directory:
+
+- `app/schemas/services/service_name/arguments.json` - Validates input arguments
+- `app/schemas/services/service_name/result.json` - Validates success response data
+
+Example `arguments.json`:
+
+```json
+{
+  "type": "object",
+  "required": ["user_id", "amount", "payment_method"],
+  "properties": {
+    "user_id": { "type": "integer" },
+    "amount": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "payment_method": {
+      "type": "string",
+      "enum": ["credit_card", "paypal", "bank_transfer"]
+    },
+    "currency": {
+      "type": "string",
+      "default": "USD"
+    }
+  },
+  "additionalProperties": false
+}
+
+```
+
+Example `result.json`:
+
+```json
+{
+  "type": "object",
+  "required": ["transaction_id", "status"],
+  "properties": {
+    "transaction_id": { "type": "string" },
+    "status": {
+      "type": "string",
+      "enum": ["approved", "pending", "declined"]
+    },
+    "receipt_url": { "type": "string" }
+  }
+}
+
+```
+
+### 2. Inline Schema Validation
+
+Alternatively, schemas can be declared directly within the service class using `ARGUMENTS_SCHEMA` and `RESULT_SCHEMA` constants.
+
+```ruby
+class Services::ProcessPayment::Service < Servus::Base
+  ARGUMENTS_SCHEMA = {
+	  type: "object",
+	  required: ["user_id", "amount", "payment_method"],
+	  properties: {
+	    user_id: { type: "integer" },
+	    amount: {
+	      type: "integer",
+	      minimum: 1
+	    },
+	    payment_method: {
+	      type: "string",
+	      enum: ["credit_card", "paypal", "bank_transfer"]
+	    },
+	    currency: {
+	      type: "string",
+	      default: "USD"
+	    }
+	  },
+	  additionalProperties: false
+	}
+
+  RESULT_SCHEMA = {
+	  type: "object",
+	  required: ["transaction_id", "status"],
+	  properties: {
+	    transaction_id: { type: "string" },
+	    status: {
+	      type: "string",
+	      enum: ["approved", "pending", "declined"]
+	    },
+	    receipt_url: { type: "string" }
+	  }
+	}
+end
+```
+
+---
+
+These schemas use JSON Schema format to enforce type safety and input/output contracts. For detailed information on authoring JSON Schema files, refer to the official specification at: https://json-schema.org/specification.html
+
+### Schema Resolution
+
+The validation system follows this precedence:
+
+1. Checks for inline schema constants (`ARGUMENTS_SCHEMA` or `RESULT_SCHEMA`)
+2. Falls back to JSON files if no inline schema is found
+3. Returns nil if neither exists
+
+### Schema Caching
+
+Both file-based and inline schemas are automatically cached:
+
+- First validation request loads and caches the schema
+- Subsequent validations use the cached version
+- Cache can be cleared using `SchemaValidation.clear_cache!`

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Servus
+  module Generators
+    # Servus Generator
+    class ServiceGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      argument :parameters, type: :array, default: [], banner: "parameter"
+
+      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
+
+      def service_path
+        "app/services/#{file_path}/service.rb"
+      end
+
+      def service_path_spec
+        "spec/services/#{file_path}/service_spec.rb"
+      end
+
+      def service_result_schema_path
+        "app/schemas/services/#{file_path}/result.json"
+      end
+
+      def service_arguments_shecma_path
+        "app/schemas/services/#{file_path}/arguments.json"
+      end
+
+      def service_class_name
+        "#{class_name}::Service"
+      end
+
+      def service_full_class_name
+        service_class_name.include?("::") ? service_class_name : "::#{service_class_name}"
+      end
+
+      def parameter_list
+        return "" if parameters.empty?
+
+        "(#{parameters.map { |param| "#{param}:" }.join(", ")})"
+      end
+
+      def initialize_params
+        parameters.map { |param| "@#{param} = #{param}" }.join("\n    ")
+      end
+
+      def attr_readers
+        return "" if parameters.empty?
+
+        "attr_reader #{parameters.map { |param| ":#{param}" }.join(", ")}"
+      end
+    end
+  end
+end

data/lib/generators/servus/service/templates/arguments.json.erb

@@ -0,0 +1,15 @@
+{
+  "type": "object",
+  "properties": {
+    <%- parameters.each do |param| %>
+      "<%= param %>": {
+        "type": "UNDECLARED_TYPE"
+      }
+    <% end %>
+  },
+  "required": [
+    <%- parameters.each do |param| %>
+      "<%= param %>",
+    <% end %>
+  ]
+}

data/lib/generators/servus/service/templates/result.json.erb

@@ -0,0 +1,4 @@
+{
+  "type": "object",
+  "properties": {}
+}

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

@@ -0,0 +1,12 @@
+module <%= class_name %>
+  class Service < Servus::ApplicationService
+    def initialize<%= parameter_list %>
+      <%= initialize_params %>
+    end
+    def call
+      # Implement service logic here
+      success({})
+    end
+    <%= attr_readers %>
+  end
+end

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

@@ -0,0 +1,9 @@
+require "rails_helper"
+
+RSpec.describe <%= service_full_class_name %> do
+  describe "#call" do
+    it "does something" do
+      # Add expectations here
+    end
+  end
+end

data/lib/servus/base.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Servus
+  class Base
+    include Servus::Support::Errors
+
+    # Support class aliases
+    Logger = Servus::Support::Logger
+    Response = Servus::Support::Response
+    Validator = Servus::Support::Validator
+
+    # Calls the service and returns a response
+    # @param args [Hash] The arguments to pass to the service
+    # @return [Servus::Support::Response] The response
+    # @raise [StandardError] If an exception is raised
+    # @raise [Servus::Support::Errors::ValidationError] If result is invalid
+    # @raise [Servus::Support::Errors::ValidationError] If arguments are invalid
+    def self.call(**args)
+      Logger.log_call(self, args)
+
+      Validator.validate_arguments!(self, args)
+
+      result = benchmark(**args) do
+        new(**args).call
+      end
+
+      Validator.validate_result!(self, result)
+
+      result
+    rescue ValidationError => e
+      Logger.log_validation_error(self, e)
+      raise e
+    rescue StandardError => e
+      Logger.log_exception(self, e)
+      raise e
+    end
+
+    # Returns a success response
+    # @param data [Object] The data to return
+    # @return [Servus::Support::Response] The success response
+    def success(data)
+      Response.new(true, data, nil)
+    end
+
+    # Returns a failure response
+    # @param message [String] The error message
+    # @param type [Class] The error type
+    # @return [Servus::Support::Response] The failure response
+    def failure(message = nil, type: Servus::Support::Errors::ServiceError)
+      error = type.new(message)
+      Response.new(false, nil, error)
+    end
+
+    # Raises an error and logs it
+    # @param message [String] The error message
+    # @param type [Class] The error type
+    # @return [void]
+    def error!(message = nil, type: Servus::Support::Errors::ServiceError)
+      Logger.log_exception(self.class, type.new(message))
+      raise type, message
+    end
+
+    # Benchmarks the call
+    # @param args [Hash] The arguments to pass to the service
+    # @return [Object] The result of the call
+    def self.benchmark(**_args)
+      start_time = Time.now.utc
+      result = yield
+      duration = Time.now.utc - start_time
+
+      Logger.log_result(self, result, duration)
+
+      result
+    end
+  end
+end

data/lib/servus/config.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Servus
+  class Config
+    # The directory where schemas are loaded from, can be set by the user
+    attr_reader :schema_root
+
+    def initialize
+      # Default to Rails.root if available, otherwise use current working directory
+      @schema_root = if defined?(Rails)
+        Rails.root.join("app/schemas/services")
+      else
+        File.expand_path("../../../app/schemas/services", __dir__)
+      end
+    end
+
+    # Returns the path for a specific service's schema
+    #
+    # @param service_namespace [String] the namespace of the service
+    # @param type [String] the type of the schema (e.g., "arguments", "result")
+    # @return [String] the path for the service's schema type
+    def schema_path_for(service_namespace, type)
+      File.join(schema_root.to_s, service_namespace, "#{type}.json")
+    end
+
+    # Returns the directory for a specific service
+    #
+    # @param service_namespace [String] the namespace of the service
+    # @return [String] the directory for the service's schemas
+    def schema_dir_for(service_namespace)
+      File.join(schema_root.to_s, service_namespace)
+    end
+  end
+
+  # Singleton config instance
+  def self.config
+    @config ||= Config.new
+  end
+
+  def self.configure
+    yield(config)
+  end
+end

data/lib/servus/railtie.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# lib/servus/railtie.rb
+require "rails/railtie"
+
+module Servus
+  class Railtie < Rails::Railtie; end
+end

data/lib/servus/support/errors.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Servus
+  module Support
+    module Errors
+      # Base error class for application services
+      # @param message [String] The error message
+      # @return [ServiceError] The error instance
+      class ServiceError < StandardError
+        attr_reader :message
+
+        DEFAULT_MESSAGE = "An error occurred"
+
+        # Initializes a new error instance
+        # @param message [String] The error message
+        # @return [ServiceError] The error instance
+        def initialize(message = nil)
+          @message = message || self.class::DEFAULT_MESSAGE
+          super("#{self.class}: #{message}")
+        end
+
+        # 404 error response
+        # @return [Hash] The error response
+        def api_error
+          { code: :bad_request, message: message }
+        end
+      end
+
+      # Error class for bad request errors
+      # @param message [String] The error message
+      # @return [BadRequestError] The error instance
+      class BadRequestError < ServiceError
+        DEFAULT_MESSAGE = "Bad request"
+
+        # 400 error response
+        # @return [Hash] The error response
+        def api_error
+          { code: :bad_request, message: message }
+        end
+      end
+
+      # Error class for authentication errors
+      # @param message [String] The error message
+      # @return [AuthenticationError] The error instance
+      class AuthenticationError < ServiceError
+        DEFAULT_MESSAGE = "Authentication failed"
+
+        # 401 error response
+        # @return [Hash] The error response
+        def api_error
+          { code: :unauthorized, message: message }
+        end
+      end
+
+      # Error class for unauthorized errors
+      # @param message [String] The error message
+      # @return [UnauthorizedError] The error instance
+      class UnauthorizedError < AuthenticationError
+        DEFAULT_MESSAGE = "Unauthorized"
+      end
+
+      # Error class for forbidden errors
+      # @param message [String] The error message
+      # @return [ForbiddenError] The error instance
+      class ForbiddenError < ServiceError
+        DEFAULT_MESSAGE = "Forbidden"
+
+        # 403 error response
+        # @return [Hash] The error response
+        def api_error
+          { code: :forbidden, message: message }
+        end
+      end
+
+      # Error class for not found errors
+      # @param message [String] The error message
+      # @return [NotFoundError] The error instance
+      class NotFoundError < ServiceError
+        DEFAULT_MESSAGE = "Not found"
+
+        # 404 error response
+        # @return [Hash] The error response
+        def api_error
+          { code: :not_found, message: message }
+        end
+      end
+
+      # Error class for unprocessable entity errors
+      # @param message [String] The error message
+      # @return [UnprocessableEntityError] The error instance
+      class UnprocessableEntityError < ServiceError
+        DEFAULT_MESSAGE = "Unprocessable entity"
+
+        # 422 error response
+        # @return [Hash] The error response
+        def api_error
+          { code: :unprocessable_entity, message: message }
+        end
+      end
+
+      # Error class for validation errors
+      # @param message [String] The error message
+      # @return [ValidationError] The error instance
+      class ValidationError < UnprocessableEntityError
+        DEFAULT_MESSAGE = "Validation failed"
+      end
+
+      # Error class for internal server errors
+      # @param message [String] The error message
+      # @return [InternalServerError] The error instance
+      class InternalServerError < ServiceError
+        DEFAULT_MESSAGE = "Internal server error"
+
+        # 500 error response
+        # @return [Hash] The error response
+        def api_error
+          { code: :internal_server_error, message: message }
+        end
+      end
+
+      # Error class for service unavailable errors
+      # @param message [String] The error message
+      # @return [ServiceUnavailableError] The error instance
+      class ServiceUnavailableError < ServiceError
+        DEFAULT_MESSAGE = "Service unavailable"
+
+        # 503 error response
+        # @return [Hash] The error response
+        def api_error
+          { code: :service_unavailable, message: message }
+        end
+      end
+    end
+  end
+end

data/lib/servus/support/logger.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Servus
+  module Support
+    class Logger
+      # Returns the logger instance depending on the environment
+      #
+      # @return [Logger] The logger instance
+      def self.logger
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger
+        else
+          @logger ||= ::Logger.new($stdout)
+        end
+      end
+
+      # Logs a call to a service
+      #
+      # @param service_class [Class] The service class
+      # @param args [Hash] The arguments passed to the service
+      def self.log_call(service_class, args)
+        logger.info("Calling #{service_class.name} with args: #{args.inspect}")
+      end
+
+      # Logs a result from a service
+      #
+      # @param service_class [Class] The service class
+      # @param result [Servus::Support::Response] The result from the service
+      # @param duration [Float] The duration of the service call
+      def self.log_result(service_class, result, duration)
+        if result.success?
+          log_success(service_class, duration)
+        else
+          log_failure(service_class, result.error, duration)
+        end
+      end
+
+      # Logs a successful result from a service
+      #
+      # @param service_class [Class] The service class
+      # @param duration [Float] The duration of the service call
+      def self.log_success(service_class, duration)
+        logger.info("#{service_class.name} succeeded in #{duration.round(3)}s")
+      end
+
+      # Logs a failed result from a service
+      #
+      # @param service_class [Class] The service class
+      # @param error [Servus::Support::Errors::ServiceError] The error from the service
+      # @param duration [Float] The duration of the service call
+      def self.log_failure(service_class, error, duration)
+        logger.warn("#{service_class.name} failed in #{duration.round(3)}s with error: #{error}")
+      end
+
+      # Logs a validation error from a service
+      #
+      # @param service_class [Class] The service class
+      # @param error [Servus::Support::Errors::ValidationError] The validation error
+      def self.log_validation_error(service_class, error)
+        logger.error("#{service_class.name} validation error: #{error.message}")
+      end
+
+      # Logs an uncaught exception from a service
+      #
+      # @param service_class [Class] The service class
+      # @param exception [Exception] The uncaught exception
+      def self.log_exception(service_class, exception)
+        logger.error("#{service_class.name} uncaught exception: #{exception.class} - #{exception.message}")
+      end
+    end
+  end
+end

data/lib/servus/support/response.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Servus
+  module Support
+    class Response
+      attr_reader :data, :error
+
+      def initialize(success, data, error)
+        @success = success
+        @data = data
+        @error = error
+      end
+
+      def success?
+        @success
+      end
+    end
+  end
+end

data/lib/servus/support/validator.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Servus
+  module Support
+    class Validator
+      # Class-level schema cache
+      @schema_cache = {}
+
+      # Validate service arguments against schema
+      def self.validate_arguments!(service_class, args)
+        schema = load_schema(service_class, "arguments")
+        return true unless schema # Skip validation if no schema exists
+
+        serialized_result = args.as_json
+        validation_errors = JSON::Validator.fully_validate(schema, serialized_result)
+
+        if validation_errors.any?
+          error_message = "Invalid arguments for #{service_class.name}: #{validation_errors.join(", ")}"
+          raise Servus::Base::ValidationError, error_message
+        end
+
+        true
+      end
+
+      # Validate service result against schema
+      def self.validate_result!(service_class, result)
+        return result unless result.success?
+
+        schema = load_schema(service_class, "result")
+        return result unless schema # Skip validation if no schema exists
+
+        serialized_result = result.data.as_json
+        validation_errors = JSON::Validator.fully_validate(schema, serialized_result)
+
+        if validation_errors.any?
+          error_message = "Invalid result structure from #{service_class.name}: #{validation_errors.join(", ")}"
+          raise Servus::Base::ValidationError, error_message
+        end
+
+        result
+      end
+
+      # Load schema from file with caching
+      def self.load_schema(service_class, type)
+        # Get service path based on class name (e.g., "process_payment" from "Servus::ProcessPayment::Service")
+        service_namespace = service_class.name.split("::")[..-2].map do |s|
+          s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+        end.join("/")
+        schema_path = Servus.config.schema_path_for(service_namespace, type)
+
+        # Return from cache if available
+        return @schema_cache[schema_path] if @schema_cache.key?(schema_path)
+
+        inline_schema_constant_name = "#{service_class}::#{type.upcase}_SCHEMA"
+        inline_schema_constant = Object.const_defined?(inline_schema_constant_name) ? Object.const_get(inline_schema_constant_name) : nil
+
+        if inline_schema_constant
+          @schema_cache[schema_path] =
+            inline_schema_constant.respond_to?(:deep_stringify_keys) ? inline_schema_constant.deep_stringify_keys : inline_schema_constant
+        elsif File.exist?(schema_path)
+          @schema_cache[schema_path] = JSON.parse(File.read(schema_path))
+        else
+          # Cache nil result to avoid checking file system again
+          @schema_cache[schema_path] = nil
+        end
+
+        @schema_cache[schema_path]
+      end
+
+      # Clear the schema cache (useful for testing or development)
+      def self.clear_cache!
+        @schema_cache = {}
+      end
+
+      # Returns the schema cache
+      def self.cache
+        @schema_cache
+      end
+    end
+  end
+end

data/lib/servus/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Servus
+  VERSION = "0.0.1"
+end

data/lib/servus.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Globals
+require "json-schema"
+require "active_model_serializers"
+
+# Servus namespace
+module Servus; end
+
+# Railtie
+require_relative "servus/railtie" if defined?(Rails::Railtie)
+
+# Config
+require_relative "servus/config"
+
+# Support
+require_relative "servus/support/logger"
+require_relative "servus/support/response"
+require_relative "servus/support/validator"
+require_relative "servus/support/errors"
+
+# Core
+require_relative "servus/version"
+require_relative "servus/base"

data/sig/servus.rbs

@@ -0,0 +1,4 @@
+module Servus
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: servus
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Sebastian Scholl
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: active_model_serializers
+  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'
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  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: A gem for managing service objects.
+email:
+- sebscholl@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- LICENSE.txt
+- READme.md
+- Rakefile
+- lib/generators/servus/service/service_generator.rb
+- lib/generators/servus/service/templates/arguments.json.erb
+- lib/generators/servus/service/templates/result.json.erb
+- lib/generators/servus/service/templates/service.rb.erb
+- lib/generators/servus/service/templates/service_spec.rb.erb
+- lib/servus.rb
+- lib/servus/base.rb
+- lib/servus/config.rb
+- lib/servus/railtie.rb
+- lib/servus/support/errors.rb
+- lib/servus/support/logger.rb
+- lib/servus/support/response.rb
+- lib/servus/support/validator.rb
+- lib/servus/version.rb
+- sig/servus.rbs
+homepage: https://github.com/zarpay/servus
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/zarpay/servus
+  source_code_uri: https://github.com/zarpay/servus
+  changelog_uri: https://github.com/zarpay/servus/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: A gem for managing service objects.
+test_files: []