servus 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f63266b1efb1e782745c67d24957ce1126b1031592667bd78fe80f5ed2c93ac7
-  data.tar.gz: 64d263185dc9214707aafc7eaaf740343e5c24311eec49db6bbccff25fa413a9
+  metadata.gz: 6f20bb1c0b41657377b94a29aef1915dc7a0c4c65442d21b9f6a60c75537dd8a
+  data.tar.gz: 9273a9d2e3efa50c3ce2d80935e7538a1fa89e0cc3195acfde974621f7960277
 SHA512:
-  metadata.gz: a6d3ff24ec58b33b926acca83447ede76c1feb54daab1ade3b4a744f66e70a87785b68d6e235934b6b20f6477e7518441486bb6d405f34cd8bfb2334c095122e
-  data.tar.gz: 5f562d3cac4a258387fab0936d8fecb41e9e42803556014d91c5802f0b27f6b5cd2a085f76b4d0d486c609f2589c286d5fe13fbd4be34270f4ecc104d2b478a1
+  metadata.gz: e2e4ec7e3390784c35acbe238b3d809c4e07859c39ccd159a1618daf3439d04d7bb4eb3c847ea30e1a3b94a1d4dfac2508601ce263160ddee1d7e0a9e20ed13b
+  data.tar.gz: 4f135793c078f9230436a6ff3f9508847469a198dfa818afadcbace146b7b85fdb78844a864538b96bded6cb3eed910002c0fdc8b6802ad4cae3189e06349a54

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.2.1] - 2025-12-20
+
+### Added
+
+- **EventHandler Scheduling Options**: Extended the `invoke` DSL to support ActiveJob scheduling options
+  - `:wait` - delay execution (e.g., `5.minutes`)
+  - `:wait_until` - schedule for specific time
+  - `:priority` - job priority
+  - `:job_options` - additional ActiveJob options
+  - Options are passed through to `call_async`, enabling delayed and scheduled event handling
+
+- **Custom HTTP Error Classes**: Added granular error classes for HTTP status handling
+  - Error classes for common HTTP statuses (400, 401, 403, 404, 409, 422, 429, 500, 502, 503, 504)
+  - Each error class has appropriate `http_status` and default `code`/`message`
+  - Enables more precise error handling and cleaner rescue blocks
+
 ## [0.2.0] - 2025-12-16
 
 ### Added

data/lib/servus/event_handler.rb

@@ -207,9 +207,9 @@ module Servus
       def collect_emitted_events
         events = Set.new
 
-        ObjectSpace.each_object(Class)
-                   .select { |klass| klass < Servus::Base }
-                   .each do |service_class|
+        services = ObjectSpace.each_object(Class).select { |klass| klass < Servus::Base }
+
+        services.each do |service_class|
           service_class.event_emissions.each_value do |emissions|
             emissions.each { |emission| events << emission[:event_name] }
           end
@@ -226,9 +226,9 @@ module Servus
       def find_orphaned_handlers(emitted_events)
         orphaned = []
 
-        ObjectSpace.each_object(Class)
-                   .select { |klass| klass < Servus::EventHandler && klass != Servus::EventHandler }
-                   .each do |handler_class|
+        handlers = ObjectSpace.each_object(Class).select { _1 < Servus::EventHandler && _1 != Servus::EventHandler }
+
+        handlers.each do |handler_class|
           next unless handler_class.event_name
           next if emitted_events.include?(handler_class.event_name)
 
@@ -245,15 +245,13 @@ module Servus
       # @return [Servus::Support::Response] the service result
       # @api private
       def invoke_service(invocation, payload)
-        service_kwargs = invocation[:mapper].call(payload)
-
-        async = invocation.dig(:options, :async) || false
-        queue = invocation.dig(:options, :queue) || nil
+        use_async = invocation.dig(:options, :async) || false
 
-        if async
-          service_kwargs = service_kwargs.merge(queue: queue) if queue
+        if use_async
+          service_kwargs = prepare_call_sync_args(invocation, payload)
           invocation[:service_class].call_async(**service_kwargs)
         else
+          service_kwargs = invocation[:mapper].call(payload)
           invocation[:service_class].call(**service_kwargs)
         end
       end
@@ -270,6 +268,23 @@ module Servus
 
         true
       end
+
+      # Prepares the service arguments by merging event payload with job options.
+      #
+      # @param invocation [Hash] the invocation configuration
+      # @param payload [Hash] the event payload
+      # @return [Hash] combined service arguments
+      def prepare_call_sync_args(invocation, payload)
+        mapper  = invocation[:mapper]
+        options = invocation[:options]
+
+        # Extract service arguments and merge with job options
+        job_opts = options.slice(:queue, :wait, :wait_until, :priority, :job_options).compact
+
+        mapper
+          .call(payload)
+          .merge(job_opts)
+      end
     end
   end
 end

data/lib/servus/support/errors.rb

@@ -54,6 +54,39 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
+      # Guard validation failure with custom code.
+      #
+      # Guards define their own error code and HTTP status via the DSL.
+      #
+      # @example
+      #   GuardError.new("Amount must be positive", code: 'invalid_amount', http_status: 422)
+      class GuardError < ServiceError
+        DEFAULT_MESSAGE = 'Guard validation failed'
+
+        # @return [String] application-specific error code
+        attr_reader :code
+
+        # @return [Symbol, Integer] HTTP status code
+        attr_reader :http_status
+
+        # Creates a new guard error with metadata.
+        #
+        # @param message [String, nil] error message
+        # @param code [String] error code for API responses (default: 'guard_failed')
+        # @param http_status [Symbol, Integer] HTTP status (default: :unprocessable_entity)
+        def initialize(message = nil, code: 'guard_failed', http_status: :unprocessable_entity)
+          super(message)
+          @code        = code
+          @http_status = http_status
+        end
+
+        def api_error = { code: code, message: message }
+      end
+
+      # --------------------------------------------------------
+      # Standard HTTP error classes
+      # --------------------------------------------------------
+
       # 400 Bad Request - malformed or invalid request data.
       class BadRequestError < ServiceError
         DEFAULT_MESSAGE = 'Bad request'
@@ -91,6 +124,126 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
+      # 405 Method Not Allowed - HTTP method not supported for this resource.
+      class MethodNotAllowedError < ServiceError
+        DEFAULT_MESSAGE = 'Method not allowed'
+
+        def http_status = :method_not_allowed
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 406 Not Acceptable - requested content type cannot be provided.
+      class NotAcceptableError < ServiceError
+        DEFAULT_MESSAGE = 'Not acceptable'
+
+        def http_status = :not_acceptable
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 407 Proxy Authentication Required - proxy credentials required.
+      class ProxyAuthenticationRequiredError < ServiceError
+        DEFAULT_MESSAGE = 'Proxy authentication required'
+
+        def http_status = :proxy_authentication_required
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 408 Request Timeout - client did not produce a request in time.
+      class RequestTimeoutError < ServiceError
+        DEFAULT_MESSAGE = 'Request timeout'
+
+        def http_status = :request_timeout
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 409 Conflict - request conflicts with current state of the resource.
+      class ConflictError < ServiceError
+        DEFAULT_MESSAGE = 'Conflict'
+
+        def http_status = :conflict
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 410 Gone - resource is no longer available and will not be available again.
+      class GoneError < ServiceError
+        DEFAULT_MESSAGE = 'Gone'
+
+        def http_status = :gone
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 411 Length Required - Content-Length header is required.
+      class LengthRequiredError < ServiceError
+        DEFAULT_MESSAGE = 'Length required'
+
+        def http_status = :length_required
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 412 Precondition Failed - precondition in headers evaluated to false.
+      class PreconditionFailedError < ServiceError
+        DEFAULT_MESSAGE = 'Precondition failed'
+
+        def http_status = :precondition_failed
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 413 Payload Too Large - request entity is larger than server limits.
+      class PayloadTooLargeError < ServiceError
+        DEFAULT_MESSAGE = 'Payload too large'
+
+        def http_status = :payload_too_large
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 414 URI Too Long - URI is too long for the server to process.
+      class UriTooLongError < ServiceError
+        DEFAULT_MESSAGE = 'URI too long'
+
+        def http_status = :uri_too_long
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 415 Unsupported Media Type - request entity has unsupported media type.
+      class UnsupportedMediaTypeError < ServiceError
+        DEFAULT_MESSAGE = 'Unsupported media type'
+
+        def http_status = :unsupported_media_type
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 416 Range Not Satisfiable - client requested a portion that cannot be supplied.
+      class RangeNotSatisfiableError < ServiceError
+        DEFAULT_MESSAGE = 'Range not satisfiable'
+
+        def http_status = :range_not_satisfiable
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 417 Expectation Failed - server cannot meet Expect header requirements.
+      class ExpectationFailedError < ServiceError
+        DEFAULT_MESSAGE = 'Expectation failed'
+
+        def http_status = :expectation_failed
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 418 I'm a Teapot - server refuses to brew coffee because it is a teapot.
+      class ImATeapotError < ServiceError
+        DEFAULT_MESSAGE = "I'm a teapot"
+
+        def http_status = :im_a_teapot
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 421 Misdirected Request - request was directed at a server unable to respond.
+      class MisdirectedRequestError < ServiceError
+        DEFAULT_MESSAGE = 'Misdirected request'
+
+        def http_status = :misdirected_request
+        def api_error = { code: http_status, message: message }
+      end
+
       # 422 Unprocessable Entity - semantic errors in request.
       class UnprocessableEntityError < ServiceError
         DEFAULT_MESSAGE = 'Unprocessable entity'
@@ -99,6 +252,14 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
+      # 422 Unprocessable Content - content could not be processed.
+      class UnprocessableContentError < UnprocessableEntityError
+        DEFAULT_MESSAGE = 'Unprocessable content'
+
+        def http_status = :unprocessable_content
+        def api_error = { code: http_status, message: message }
+      end
+
       # 422 Validation Error - schema or business validation failed.
       class ValidationError < UnprocessableEntityError
         DEFAULT_MESSAGE = 'Validation failed'
@@ -106,33 +267,68 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
-      # Guard validation failure with custom code.
-      #
-      # Guards define their own error code and HTTP status via the DSL.
-      #
-      # @example
-      #   GuardError.new("Amount must be positive", code: 'invalid_amount', http_status: 422)
-      class GuardError < ServiceError
-        DEFAULT_MESSAGE = 'Guard validation failed'
+      # 423 Locked - resource is locked.
+      class LockedError < ServiceError
+        DEFAULT_MESSAGE = 'Locked'
 
-        # @return [String] application-specific error code
-        attr_reader :code
+        def http_status = :locked
+        def api_error = { code: http_status, message: message }
+      end
 
-        # @return [Symbol, Integer] HTTP status code
-        attr_reader :http_status
+      # 424 Failed Dependency - request failed due to failure of a previous request.
+      class FailedDependencyError < ServiceError
+        DEFAULT_MESSAGE = 'Failed dependency'
 
-        # Creates a new guard error with metadata.
-        #
-        # @param message [String, nil] error message
-        # @param code [String] error code for API responses (default: 'guard_failed')
-        # @param http_status [Symbol, Integer] HTTP status (default: :unprocessable_entity)
-        def initialize(message = nil, code: 'guard_failed', http_status: :unprocessable_entity)
-          super(message)
-          @code        = code
-          @http_status = http_status
-        end
+        def http_status = :failed_dependency
+        def api_error = { code: http_status, message: message }
+      end
 
-        def api_error = { code: code, message: message }
+      # 425 Too Early - server unwilling to process request that might be replayed.
+      class TooEarlyError < ServiceError
+        DEFAULT_MESSAGE = 'Too early'
+
+        def http_status = :too_early
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 426 Upgrade Required - client should switch to a different protocol.
+      class UpgradeRequiredError < ServiceError
+        DEFAULT_MESSAGE = 'Upgrade required'
+
+        def http_status = :upgrade_required
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 428 Precondition Required - origin server requires the request to be conditional.
+      class PreconditionRequiredError < ServiceError
+        DEFAULT_MESSAGE = 'Precondition required'
+
+        def http_status = :precondition_required
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 429 Too Many Requests - user has sent too many requests in a given time.
+      class TooManyRequestsError < ServiceError
+        DEFAULT_MESSAGE = 'Too many requests'
+
+        def http_status = :too_many_requests
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 431 Request Header Fields Too Large - server unwilling to process due to header size.
+      class RequestHeaderFieldsTooLargeError < ServiceError
+        DEFAULT_MESSAGE = 'Request header fields too large'
+
+        def http_status = :request_header_fields_too_large
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 451 Unavailable For Legal Reasons - resource unavailable due to legal demands.
+      class UnavailableForLegalReasonsError < ServiceError
+        DEFAULT_MESSAGE = 'Unavailable for legal reasons'
+
+        def http_status = :unavailable_for_legal_reasons
+        def api_error = { code: http_status, message: message }
       end
 
       # 500 Internal Server Error - unexpected server-side failure.
@@ -143,6 +339,22 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
+      # 501 Not Implemented - server does not support the functionality required.
+      class NotImplementedError < ServiceError
+        DEFAULT_MESSAGE = 'Not implemented'
+
+        def http_status = :not_implemented
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 502 Bad Gateway - server received an invalid response from upstream.
+      class BadGatewayError < ServiceError
+        DEFAULT_MESSAGE = 'Bad gateway'
+
+        def http_status = :bad_gateway
+        def api_error = { code: http_status, message: message }
+      end
+
       # 503 Service Unavailable - dependency temporarily unavailable.
       class ServiceUnavailableError < ServiceError
         DEFAULT_MESSAGE = 'Service unavailable'
@@ -150,6 +362,62 @@ module Servus
         def http_status = :service_unavailable
         def api_error = { code: http_status, message: message }
       end
+
+      # 504 Gateway Timeout - upstream server did not respond in time.
+      class GatewayTimeoutError < ServiceError
+        DEFAULT_MESSAGE = 'Gateway timeout'
+
+        def http_status = :gateway_timeout
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 505 HTTP Version Not Supported - server does not support the HTTP version.
+      class HttpVersionNotSupportedError < ServiceError
+        DEFAULT_MESSAGE = 'HTTP version not supported'
+
+        def http_status = :http_version_not_supported
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 506 Variant Also Negotiates - transparent content negotiation error.
+      class VariantAlsoNegotiatesError < ServiceError
+        DEFAULT_MESSAGE = 'Variant also negotiates'
+
+        def http_status = :variant_also_negotiates
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 507 Insufficient Storage - server unable to store the representation.
+      class InsufficientStorageError < ServiceError
+        DEFAULT_MESSAGE = 'Insufficient storage'
+
+        def http_status = :insufficient_storage
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 508 Loop Detected - server detected an infinite loop while processing.
+      class LoopDetectedError < ServiceError
+        DEFAULT_MESSAGE = 'Loop detected'
+
+        def http_status = :loop_detected
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 510 Not Extended - further extensions to the request are required.
+      class NotExtendedError < ServiceError
+        DEFAULT_MESSAGE = 'Not extended'
+
+        def http_status = :not_extended
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 511 Network Authentication Required - client needs to authenticate for network access.
+      class NetworkAuthenticationRequiredError < ServiceError
+        DEFAULT_MESSAGE = 'Network authentication required'
+
+        def http_status = :network_authentication_required
+        def api_error = { code: http_status, message: message }
+      end
     end
   end
 end

data/lib/servus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Servus
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: servus
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Sebastian Scholl