servus 0.2.1 → 0.4.0

data/lib/servus.rb

@@ -20,10 +20,12 @@ require_relative 'servus/config'
 
 # Support
 require_relative 'servus/support/logger'
+require_relative 'servus/support/data_object'
 require_relative 'servus/support/response'
 require_relative 'servus/support/validator'
 require_relative 'servus/support/errors'
 require_relative 'servus/support/rescuer'
+require_relative 'servus/support/lockdown'
 require_relative 'servus/support/message_resolver'
 
 # Events

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: servus
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Sebastian Scholl
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_model_serializers
@@ -27,14 +28,14 @@ dependencies:
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
 - !ruby/object:Gem::Dependency
@@ -55,14 +56,14 @@ dependencies:
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
 description: Servus is a Ruby gem that provides a structured way to create and manage
@@ -74,113 +75,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".claude/commands/check-docs.md"
-- ".claude/commands/consistency-check.md"
-- ".claude/commands/fine-tooth-comb.md"
-- ".claude/commands/red-green-refactor.md"
-- ".claude/settings.json"
-- ".rspec"
-- ".rubocop.yml"
-- ".yardopts"
-- CHANGELOG.md
-- CLAUDE.md
-- IDEAS.md
-- LICENSE.txt
-- READme.md
-- Rakefile
-- docs/core/1_overview.md
-- docs/core/2_architecture.md
-- docs/core/3_service_objects.md
-- docs/features/1_schema_validation.md
-- docs/features/2_error_handling.md
-- docs/features/3_async_execution.md
-- docs/features/4_logging.md
-- docs/features/5_event_bus.md
-- docs/features/6_guards.md
-- docs/features/guards_naming_convention.md
-- docs/guides/1_common_patterns.md
-- docs/guides/2_migration_guide.md
-- docs/integration/1_configuration.md
-- docs/integration/2_testing.md
-- docs/integration/3_rails_integration.md
-- docs/yard/Servus.html
-- docs/yard/Servus/Base.html
-- docs/yard/Servus/Config.html
-- docs/yard/Servus/Extensions.html
-- docs/yard/Servus/Extensions/Async.html
-- docs/yard/Servus/Extensions/Async/Call.html
-- docs/yard/Servus/Extensions/Async/Errors.html
-- docs/yard/Servus/Extensions/Async/Errors/AsyncError.html
-- docs/yard/Servus/Extensions/Async/Errors/JobEnqueueError.html
-- docs/yard/Servus/Extensions/Async/Errors/ServiceNotFoundError.html
-- docs/yard/Servus/Extensions/Async/Ext.html
-- docs/yard/Servus/Extensions/Async/Job.html
-- docs/yard/Servus/Generators.html
-- docs/yard/Servus/Generators/ServiceGenerator.html
-- docs/yard/Servus/Helpers.html
-- docs/yard/Servus/Helpers/ControllerHelpers.html
-- docs/yard/Servus/Railtie.html
-- docs/yard/Servus/Support.html
-- docs/yard/Servus/Support/Errors.html
-- docs/yard/Servus/Support/Errors/AuthenticationError.html
-- docs/yard/Servus/Support/Errors/BadRequestError.html
-- docs/yard/Servus/Support/Errors/ForbiddenError.html
-- docs/yard/Servus/Support/Errors/InternalServerError.html
-- docs/yard/Servus/Support/Errors/NotFoundError.html
-- docs/yard/Servus/Support/Errors/ServiceError.html
-- docs/yard/Servus/Support/Errors/ServiceUnavailableError.html
-- docs/yard/Servus/Support/Errors/UnauthorizedError.html
-- docs/yard/Servus/Support/Errors/UnprocessableEntityError.html
-- docs/yard/Servus/Support/Errors/ValidationError.html
-- docs/yard/Servus/Support/Logger.html
-- docs/yard/Servus/Support/Rescuer.html
-- docs/yard/Servus/Support/Rescuer/BlockContext.html
-- docs/yard/Servus/Support/Rescuer/CallOverride.html
-- docs/yard/Servus/Support/Rescuer/ClassMethods.html
-- docs/yard/Servus/Support/Response.html
-- docs/yard/Servus/Support/Validator.html
-- docs/yard/Servus/Testing.html
-- docs/yard/Servus/Testing/ExampleBuilders.html
-- docs/yard/Servus/Testing/ExampleExtractor.html
-- docs/yard/_index.html
-- docs/yard/class_list.html
-- docs/yard/css/common.css
-- docs/yard/css/full_list.css
-- docs/yard/css/style.css
-- docs/yard/file.1_common_patterns.html
-- docs/yard/file.1_configuration.html
-- docs/yard/file.1_overview.html
-- docs/yard/file.1_schema_validation.html
-- docs/yard/file.2_architecture.html
-- docs/yard/file.2_error_handling.html
-- docs/yard/file.2_migration_guide.html
-- docs/yard/file.2_testing.html
-- docs/yard/file.3_async_execution.html
-- docs/yard/file.3_rails_integration.html
-- docs/yard/file.3_service_objects.html
-- docs/yard/file.4_logging.html
-- docs/yard/file.ErrorHandling.html
-- docs/yard/file.READme.html
-- docs/yard/file.architecture.html
-- docs/yard/file.async_execution.html
-- docs/yard/file.common_patterns.html
-- docs/yard/file.configuration.html
-- docs/yard/file.error_handling.html
-- docs/yard/file.logging.html
-- docs/yard/file.migration_guide.html
-- docs/yard/file.overview.html
-- docs/yard/file.rails_integration.html
-- docs/yard/file.schema_validation.html
-- docs/yard/file.service_objects.html
-- docs/yard/file.testing.html
-- docs/yard/file_list.html
-- docs/yard/frames.html
-- docs/yard/index.html
-- docs/yard/js/app.js
-- docs/yard/js/full_list.js
-- docs/yard/js/jquery.js
-- docs/yard/method_list.html
-- docs/yard/top-level-namespace.html
 - lib/generators/servus/event_handler/event_handler_generator.rb
 - lib/generators/servus/event_handler/templates/handler.rb.erb
 - lib/generators/servus/event_handler/templates/handler_spec.rb.erb
@@ -203,6 +97,10 @@ files:
 - lib/servus/extensions/async/errors.rb
 - lib/servus/extensions/async/ext.rb
 - lib/servus/extensions/async/job.rb
+- lib/servus/extensions/lazily/call.rb
+- lib/servus/extensions/lazily/errors.rb
+- lib/servus/extensions/lazily/ext.rb
+- lib/servus/extensions/lazily/resolver.rb
 - lib/servus/guard.rb
 - lib/servus/guards.rb
 - lib/servus/guards/falsey_guard.rb
@@ -211,7 +109,9 @@ files:
 - lib/servus/guards/truthy_guard.rb
 - lib/servus/helpers/controller_helpers.rb
 - lib/servus/railtie.rb
+- lib/servus/support/data_object.rb
 - lib/servus/support/errors.rb
+- lib/servus/support/lockdown.rb
 - lib/servus/support/logger.rb
 - lib/servus/support/message_resolver.rb
 - lib/servus/support/rescuer.rb
@@ -231,6 +131,7 @@ metadata:
   source_code_uri: https://github.com/zarpay/servus
   changelog_uri: https://github.com/zarpay/servus/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -245,7 +146,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: A gem for managing service objects.
 test_files: []

data/.claude/commands/check-docs.md

@@ -1 +0,0 @@
-Scan the documentation in docs/ then check the current git changeset. If the changeset has modifications that might affect the documentation, then review the related documentation and make any necessary updates.

data/.claude/commands/consistency-check.md

@@ -1 +0,0 @@
-Are the latest changes consistent with the way that similar functionality has been implemented in the rest of the codebase? #$ARGUMENTS

data/.claude/commands/fine-tooth-comb.md

@@ -1 +0,0 @@
-We're going to go over #$ARGUMENTS with a fine-tooth comb. I want detailed explanations and no edits unless I ask for them. Start by identifying the first thing that looks wrong and explain why.

data/.claude/commands/red-green-refactor.md

@@ -1,5 +0,0 @@
-During this session we will be practicing TDD in the red-green-refactor cycle. The first step in the cycle is to write a test for the smallest possible unit of functionality. Once the test is written, run the test and it should fail. This is the red phase. The next step is to write the code to make the test pass. This is the green phase. Once the test passes, the code is refactored to be more readable and maintainable. This is the refactor phase.
-
-If we get into a situation where more than one test fails, we will focus on the test that is most important to fix first. During that fix phase, we will only run the test that is failing until it passes.
-
-While we're in this mode, you will not use your TODO tool to track tasks. You will rely on me (the human user) to tell you what the next step is.

data/.claude/settings.json

@@ -1,24 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(bundle exec rspec:*)",
-      "Bash(bundle exec rubocop:*)",
-      "Bash(find:*)"
-    ],
-    "deny": [],
-    "ask": []
-  },
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bundle exec rubocop -A"
-          }
-        ]
-      }
-    ]
-  }
-}

data/.rspec

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

data/.rubocop.yml

@@ -1,27 +0,0 @@
-AllCops:
-  NewCops: enable
-  TargetRubyVersion: 3.3
-  Include:
-    - 'lib/**/*.rb'
-    - 'spec/**/*.rb'
-  Exclude:
-    - 'spec/dummy/**/*'
-    - 'vendor/bundle/**/*'
-
-Lint/ConstantDefinitionInBlock:
-  Enabled: false
-
-Lint/ConstantReassignment:
-  Exclude:
-    - 'spec/**/*'
-
-Lint/MissingSuper:
-  Exclude:
-    - 'spec/**/*'
-
-Metrics/BlockLength:
-  Exclude:
-    - 'spec/**/*'
-
-Naming/PredicateMethod:
-  Enabled: false

data/.yardopts

@@ -1,6 +0,0 @@
---output-dir ./docs/yard
---readme READme.md
---files docs/**/*.md
---markup markdown
---markup-provider redcarpet
---title "Servus | Service Object Framework"

data/CHANGELOG.md

@@ -1,122 +0,0 @@
-## [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
-
-- **Guards System**: Reusable validation rules with rich error responses
-  - `Servus::Guard` base class for creating custom guards
-  - `Servus::Guards` module included in services with `enforce_*!` and `check_*?` methods
-  - Built-in guards:
-    - `PresenceGuard` - validates values are present (not nil or empty)
-    - `TruthyGuard` - validates object attributes are truthy
-    - `FalseyGuard` - validates object attributes are falsey
-    - `StateGuard` - validates object attributes match expected value(s)
-  - Guards auto-define methods when classes inherit from `Servus::Guard`
-  - Guard DSL: `http_status`, `error_code`, `message` with interpolation support
-  - Multiple message template formats: String, I18n Symbol, inline Hash, Proc
-  - Rails auto-loading from `app/guards/*_guard.rb`
-  - Configuration options: `guards_dir`, `include_default_guards`
-
-- **GuardError**: New error class for guard validation failures
-  - Custom `code` and `http_status` per guard
-  - Services catch `:guard_failure` and wrap in failure response automatically
-
-### Changed
-
-- **Error API Refactored**: Cleaner separation of HTTP status and error body
-  - All errors now have `http_status` method returning Rails status symbol
-  - `api_error` returns `{ code:, message: }` for response body only
-  - Follows community conventions (Stripe, JSON:API) where HTTP status is in header
-
-- **Controller Helpers Refactored**:
-  - Renamed `render_service_object_error` to `render_service_error`
-  - Now takes error object directly instead of `api_error` hash
-  - Response format: `{ error: { code:, message: } }` with status from `error.http_status`
-
-### Breaking Changes
-
-- `render_service_object_error` renamed to `render_service_error`
-- `render_service_error` now accepts error object, not hash: `render_service_error(result.error)` instead of `render_service_error(result.error.api_error)`
-- Error response JSON structure changed from `{ code:, message: }` to `{ error: { code:, message: } }`
-
-## [0.1.6] - 2025-12-06
-
-### Fixed
-
-- Make `emit_events_for` public in `Servus::Events::Emitter` to allow external event emission
-
-## [0.1.5] - 2025-12-03
-
-### Added
-
-- **Event Bus Architecture**: Introduced event-driven architecture for decoupling service logic from side effects
-  - `Servus::EventHandler` base class for creating event handlers that subscribe to events and invoke services
-  - `emits` DSL on `Servus::Base` for declaring events that fire on `:success`, `:failure`, or `:error!`
-  - `Servus::Events::Bus` for routing events to handlers via ActiveSupport::Notifications
-  - Rails generator: `rails g servus:event_handler event_name` creates handler and spec files
-  - Event handlers auto-load from `app/events/` directory in Rails applications
-
-- **Event Payload Validation**: JSON Schema validation for event payloads
-  - `schema payload: {...}` DSL on EventHandler for declaring payload schemas
-  - Validation occurs when events are emitted via `EventHandler.emit(payload)`
-
-- **Event Testing Matchers**: RSpec matchers for testing event emission
-  - `emit_event(:event_name)` matcher to assert events are emitted
-  - `emit_event(:event_name).with(payload)` for payload assertions
-  - `call_service(ServiceClass).with(args)` matcher for handler testing
-  - `call_service(ServiceClass).async` for async invocation testing
-
-- **Configuration Options**: New and updated configuration settings
-  - `config.schemas_dir` - Directory for JSON schema files (default: `app/schemas`)
-  - `config.services_dir` - Directory for service files (default: `app/services`)
-  - `config.events_dir` - Directory for event handlers (default: `app/events`)
-  - `config.strict_event_validation` - Validate handlers subscribe to emitted events (default: `true`)
-  - `Servus::EventHandler.validate_all_handlers!` for CI validation of handler-event mappings
-
-- **Generator Improvements**: Enhanced service and event handler generators
-  - Service templates now include comprehensive YARD documentation
-  - Service spec templates include example test patterns
-  - JSON schema templates include proper structure with `$schema` reference
-  - Event handler templates include full documentation and examples
-  - `--no-docs` flag to skip documentation comments in generated files
-
-### Changed
-
-- Updated execution flow to include event emission after result validation
-- Enhanced Railtie to auto-load event handlers and clear the event bus on reload in development
-
-## [0.1.4] - 2025-11-21
-- Added: Test helpers (`servus_arguments_example` and `servus_result_example`) to extract example values from schemas for testing
-- Added: YARD documentation configuration with README homepage and markdown file support
-- Added: Added `schema` DSL method for cleaner schema definition. Supports `schema arguments: {...}, result: {...}` syntax. Fully backwards compatible with existing `ARGUMENTS_SCHEMA` and `RESULT_SCHEMA` constants.
-- Added: Added support from blocks on `rescue_from` to override default failure handler.
-- Fixed: YARD link resolution warnings in documentation
-
-## [0.1.3] - 2025-10-10
-- Added: Added `call_async` method to `Servus::Base` to enqueue a job for calling the service asynchronously
-- Added: Added `Async::Job` to handle async enqueing with support for ActiveJob set options
-
-## [0.1.1] - 2025-08-20
-
-- Added: Added `rescue_from` method to `Servus::Base` to rescue from standard errors and use custom error types.
-- Added: Added `run_service` and `render_service_object_error` helpers to `Servus::Helpers::ControllerHelpers`.
-- Fixed: All rubocop warnings.
-
-## [0.1.0] - 2025-04-28
-
-- Initial release

data/CLAUDE.md

@@ -1,10 +0,0 @@
-Before starting a session, always review the latest docs in the following order:
-
-1. `/docs/core/**/*.md`
-2. `/docs/features/**/*.md`
-3. `/docs/guides/**/*.md`
-4. `/docs/integration/**/*.md`
-
-Focus on writing code consistent with the rest of the project. Use existing files as references for conventions and style.
-
-Ensure new code always encludes world class YARD documentation. If documentation looks out of date or incomplete, suggest a relevant edit.

data/IDEAS.md

@@ -1,5 +0,0 @@
-1. Make sure Async Jobs don't retry when the job class cant be constantized.
-
-2. Improve error handling with an error registry that can be referenced by codes as opposed to fully qualified class names.
-
-3. Update generators to not make schema files and instead add schemas to schema: method in generators.

data/LICENSE.txt

@@ -1,21 +0,0 @@
-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.