servus 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +6 -0
  3. data/CHANGELOG.md +8 -1
  4. data/IDEAS.md +5 -0
  5. data/READme.md +147 -42
  6. data/Rakefile +33 -0
  7. data/builds/servus-0.1.2.gem +0 -0
  8. data/builds/servus-0.1.3.gem +0 -0
  9. data/builds/servus-0.1.4.gem +0 -0
  10. data/docs/core/1_overview.md +77 -0
  11. data/docs/core/2_architecture.md +92 -0
  12. data/docs/core/3_service_objects.md +121 -0
  13. data/docs/features/1_schema_validation.md +119 -0
  14. data/docs/features/2_error_handling.md +121 -0
  15. data/docs/features/3_async_execution.md +81 -0
  16. data/docs/features/4_logging.md +64 -0
  17. data/docs/guides/1_common_patterns.md +90 -0
  18. data/docs/guides/2_migration_guide.md +175 -0
  19. data/docs/integration/1_configuration.md +51 -0
  20. data/docs/integration/2_testing.md +164 -0
  21. data/docs/integration/3_rails_integration.md +99 -0
  22. data/docs/yard/Servus/Base.html +1645 -0
  23. data/docs/yard/Servus/Config.html +582 -0
  24. data/docs/yard/Servus/Extensions/Async/Call.html +400 -0
  25. data/docs/yard/Servus/Extensions/Async/Errors/AsyncError.html +140 -0
  26. data/docs/yard/Servus/Extensions/Async/Errors/JobEnqueueError.html +154 -0
  27. data/docs/yard/Servus/Extensions/Async/Errors/ServiceNotFoundError.html +154 -0
  28. data/docs/yard/Servus/Extensions/Async/Errors.html +128 -0
  29. data/docs/yard/Servus/Extensions/Async/Ext.html +119 -0
  30. data/docs/yard/Servus/Extensions/Async/Job.html +310 -0
  31. data/docs/yard/Servus/Extensions/Async.html +141 -0
  32. data/docs/yard/Servus/Extensions.html +117 -0
  33. data/docs/yard/Servus/Generators/ServiceGenerator.html +261 -0
  34. data/docs/yard/Servus/Generators.html +115 -0
  35. data/docs/yard/Servus/Helpers/ControllerHelpers.html +457 -0
  36. data/docs/yard/Servus/Helpers.html +115 -0
  37. data/docs/yard/Servus/Railtie.html +134 -0
  38. data/docs/yard/Servus/Support/Errors/AuthenticationError.html +287 -0
  39. data/docs/yard/Servus/Support/Errors/BadRequestError.html +283 -0
  40. data/docs/yard/Servus/Support/Errors/ForbiddenError.html +284 -0
  41. data/docs/yard/Servus/Support/Errors/InternalServerError.html +283 -0
  42. data/docs/yard/Servus/Support/Errors/NotFoundError.html +284 -0
  43. data/docs/yard/Servus/Support/Errors/ServiceError.html +489 -0
  44. data/docs/yard/Servus/Support/Errors/ServiceUnavailableError.html +290 -0
  45. data/docs/yard/Servus/Support/Errors/UnauthorizedError.html +200 -0
  46. data/docs/yard/Servus/Support/Errors/UnprocessableEntityError.html +288 -0
  47. data/docs/yard/Servus/Support/Errors/ValidationError.html +200 -0
  48. data/docs/yard/Servus/Support/Errors.html +140 -0
  49. data/docs/yard/Servus/Support/Logger.html +856 -0
  50. data/docs/yard/Servus/Support/Rescuer/BlockContext.html +585 -0
  51. data/docs/yard/Servus/Support/Rescuer/CallOverride.html +257 -0
  52. data/docs/yard/Servus/Support/Rescuer/ClassMethods.html +343 -0
  53. data/docs/yard/Servus/Support/Rescuer.html +267 -0
  54. data/docs/yard/Servus/Support/Response.html +574 -0
  55. data/docs/yard/Servus/Support/Validator.html +1150 -0
  56. data/docs/yard/Servus/Support.html +119 -0
  57. data/docs/yard/Servus/Testing/ExampleBuilders.html +523 -0
  58. data/docs/yard/Servus/Testing/ExampleExtractor.html +578 -0
  59. data/docs/yard/Servus/Testing.html +142 -0
  60. data/docs/yard/Servus.html +343 -0
  61. data/docs/yard/_index.html +535 -0
  62. data/docs/yard/class_list.html +54 -0
  63. data/docs/yard/css/common.css +1 -0
  64. data/docs/yard/css/full_list.css +58 -0
  65. data/docs/yard/css/style.css +503 -0
  66. data/docs/yard/file.1_common_patterns.html +154 -0
  67. data/docs/yard/file.1_configuration.html +115 -0
  68. data/docs/yard/file.1_overview.html +142 -0
  69. data/docs/yard/file.1_schema_validation.html +188 -0
  70. data/docs/yard/file.2_architecture.html +157 -0
  71. data/docs/yard/file.2_error_handling.html +190 -0
  72. data/docs/yard/file.2_migration_guide.html +242 -0
  73. data/docs/yard/file.2_testing.html +227 -0
  74. data/docs/yard/file.3_async_execution.html +145 -0
  75. data/docs/yard/file.3_rails_integration.html +160 -0
  76. data/docs/yard/file.3_service_objects.html +191 -0
  77. data/docs/yard/file.4_logging.html +135 -0
  78. data/docs/yard/file.ErrorHandling.html +190 -0
  79. data/docs/yard/file.READme.html +674 -0
  80. data/docs/yard/file.architecture.html +157 -0
  81. data/docs/yard/file.async_execution.html +145 -0
  82. data/docs/yard/file.common_patterns.html +154 -0
  83. data/docs/yard/file.configuration.html +115 -0
  84. data/docs/yard/file.error_handling.html +190 -0
  85. data/docs/yard/file.logging.html +135 -0
  86. data/docs/yard/file.migration_guide.html +242 -0
  87. data/docs/yard/file.overview.html +142 -0
  88. data/docs/yard/file.rails_integration.html +160 -0
  89. data/docs/yard/file.schema_validation.html +188 -0
  90. data/docs/yard/file.service_objects.html +191 -0
  91. data/docs/yard/file.testing.html +227 -0
  92. data/docs/yard/file_list.html +119 -0
  93. data/docs/yard/frames.html +22 -0
  94. data/docs/yard/index.html +674 -0
  95. data/docs/yard/js/app.js +344 -0
  96. data/docs/yard/js/full_list.js +242 -0
  97. data/docs/yard/js/jquery.js +4 -0
  98. data/docs/yard/method_list.html +542 -0
  99. data/docs/yard/top-level-namespace.html +110 -0
  100. data/lib/generators/servus/service/service_generator.rb +64 -1
  101. data/lib/generators/servus/service/templates/service.rb.erb +1 -1
  102. data/lib/servus/base.rb +258 -57
  103. data/lib/servus/config.rb +58 -12
  104. data/lib/servus/extensions/async/call.rb +50 -18
  105. data/lib/servus/extensions/async/errors.rb +23 -3
  106. data/lib/servus/extensions/async/ext.rb +10 -2
  107. data/lib/servus/extensions/async/job.rb +32 -11
  108. data/lib/servus/helpers/controller_helpers.rb +73 -37
  109. data/lib/servus/support/errors.rb +135 -45
  110. data/lib/servus/support/rescuer.rb +189 -36
  111. data/lib/servus/support/response.rb +49 -7
  112. data/lib/servus/support/validator.rb +120 -19
  113. data/lib/servus/testing/example_builders.rb +133 -0
  114. data/lib/servus/testing/example_extractor.rb +309 -0
  115. data/lib/servus/testing.rb +17 -0
  116. data/lib/servus/version.rb +1 -1
  117. metadata +118 -19
data/docs/yard/file.overview.html ADDED
@@ -0,0 +1,142 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>
7
+ File: Core / Overview
8
+
9
+ &mdash; Servus | Service Object Framework
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" />
16
+
17
+ <script type="text/javascript">
18
+ pathId = "overview";
19
+ relpath = '';
20
+ </script>
21
+
22
+
23
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
24
+
25
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
26
+
27
+
28
+ </head>
29
+ <body>
30
+ <div class="nav_wrap">
31
+ <iframe id="nav" src="file_list.html?1"></iframe>
32
+ <div id="resizer"></div>
33
+ </div>
34
+
35
+ <div id="main" tabindex="-1">
36
+ <div id="header">
37
+ <div id="menu">
38
+
39
+ <a href="_index.html">Index</a> &raquo;
40
+ <span class="title">File: Core / Overview</span>
41
+
42
+ </div>
43
+
44
+ <div id="search">
45
+
46
+ <a class="full_list_link" id="class_list_link"
47
+ href="class_list.html">
48
+
49
+ <svg width="24" height="24">
50
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
51
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
52
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
53
+ </svg>
54
+ </a>
55
+
56
+ </div>
57
+ <div class="clear"></div>
58
+ </div>
59
+
60
+ <div id="content"><div id='filecontents'><h1 id="servus-overview">Servus Overview</h1>
61
+
62
+ <p>Servus is a lightweight framework for implementing service objects in Ruby applications. It extracts business logic from controllers and models into testable, single-purpose classes with built-in validation, error handling, and logging.</p>
63
+
64
+ <h2 id="core-concepts">Core Concepts</h2>
65
+
66
+ <h3 id="the-service-pattern">The Service Pattern</h3>
67
+
68
+ <p>Services encapsulate one business operation. Each service inherits from <code>Servus::Base</code>, implements <code>initialize</code> and <code>call</code>, and returns a <code>Response</code> object indicating success or failure.</p>
69
+
70
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>ProcessPayment</span><span class='op'>::</span><span class='const'>Service</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Base.html" title="Servus::Base (class)">Base</a></span></span>
71
+ <span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='label'>user_id:</span><span class='comma'>,</span> <span class='label'>amount:</span><span class='rparen'>)</span>
72
+ <span class='ivar'>@user_id</span> <span class='op'>=</span> <span class='id identifier rubyid_user_id'>user_id</span>
73
+ <span class='ivar'>@amount</span> <span class='op'>=</span> <span class='id identifier rubyid_amount'>amount</span>
74
+ <span class='kw'>end</span>
75
+
76
+ <span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
77
+ <span class='id identifier rubyid_user'>user</span> <span class='op'>=</span> <span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='ivar'>@user_id</span><span class='rparen'>)</span>
78
+ <span class='kw'>return</span> <span class='id identifier rubyid_failure'>failure</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Insufficient funds</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span> <span class='kw'>unless</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_balance'>balance</span> <span class='op'>&gt;=</span> <span class='ivar'>@amount</span>
79
+
80
+ <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_update!'>update!</span><span class='lparen'>(</span><span class='label'>balance:</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_balance'>balance</span> <span class='op'>-</span> <span class='ivar'>@amount</span><span class='rparen'>)</span>
81
+ <span class='id identifier rubyid_success'>success</span><span class='lparen'>(</span><span class='label'>user:</span> <span class='id identifier rubyid_user'>user</span><span class='comma'>,</span> <span class='label'>new_balance:</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_balance'>balance</span><span class='rparen'>)</span>
82
+ <span class='kw'>end</span>
83
+ <span class='kw'>end</span>
84
+
85
+ <span class='comment'># Usage
86
+ </span><span class='id identifier rubyid_result'>result</span> <span class='op'>=</span> <span class='const'>ProcessPayment</span><span class='op'>::</span><span class='const'>Service</span><span class='period'>.</span><span class='id identifier rubyid_call'>call</span><span class='lparen'>(</span><span class='label'>user_id:</span> <span class='int'>1</span><span class='comma'>,</span> <span class='label'>amount:</span> <span class='int'>50</span><span class='rparen'>)</span>
87
+ <span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span> <span class='comment'># =&gt; true
88
+ </span><span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_data'>data</span> <span class='comment'># =&gt; { user: #&lt;User&gt;, new_balance: 950 }
89
+ </span></code></pre>
90
+
91
+ <h3 id="response-objects">Response Objects</h3>
92
+
93
+ <p>Services return <code>Response</code> objects instead of raising exceptions for business failures. This makes success and failure paths explicit and enables service composition without exception handling.</p>
94
+
95
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_result'>result</span> <span class='op'>=</span> <span class='const'>SomeService</span><span class='period'>.</span><span class='id identifier rubyid_call'>call</span><span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span><span class='rparen'>)</span>
96
+ <span class='kw'>if</span> <span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span>
97
+ <span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_data'>data</span> <span class='comment'># Hash or object returned by success()
98
+ </span><span class='kw'>else</span>
99
+ <span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_error'>error</span> <span class='comment'># ServiceError instance
100
+ </span> <span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_error'>error</span><span class='period'>.</span><span class='id identifier rubyid_message'>message</span>
101
+ <span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_error'>error</span><span class='period'>.</span><span class='id identifier rubyid_api_error'>api_error</span> <span class='comment'># { code: :symbol, message: &quot;string&quot; }
102
+ </span><span class='kw'>end</span>
103
+ </code></pre>
104
+
105
+ <h3 id="optional-schema-validation">Optional Schema Validation</h3>
106
+
107
+ <p>Services can define JSON schemas for arguments and results. Validation happens automatically before/after execution but is entirely optional.</p>
108
+
109
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>Service</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Base.html" title="Servus::Base (class)">Base</a></span></span>
110
+ <span class='id identifier rubyid_schema'>schema</span><span class='lparen'>(</span>
111
+ <span class='label'>arguments:</span> <span class='lbrace'>{</span>
112
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>object</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
113
+ <span class='label'>required:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>user_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>amount</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
114
+ <span class='label'>properties:</span> <span class='lbrace'>{</span>
115
+ <span class='label'>user_id:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>integer</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
116
+ <span class='label'>amount:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>number</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>minimum:</span> <span class='float'>0.01</span> <span class='rbrace'>}</span>
117
+ <span class='rbrace'>}</span>
118
+ <span class='rbrace'>}</span>
119
+ <span class='rparen'>)</span>
120
+ <span class='kw'>end</span>
121
+ </code></pre>
122
+
123
+ <h2 id="when-to-use-servus">When to Use Servus</h2>
124
+
125
+ <p><strong>Good fits</strong>: Multi-step workflows, operations spanning multiple models, external API calls, background jobs, complex business logic.</p>
126
+
127
+ <p><strong>Poor fits</strong>: Simple CRUD, single-model operations, operations tightly coupled to one model.</p>
128
+
129
+ <h2 id="framework-integration">Framework Integration</h2>
130
+
131
+ <p>Servus core works in any Ruby application. Rails-specific features (async via ActiveJob, controller helpers, generators) are optional additions. Services work without any configuration - just inherit from <code>Servus::Base</code> and implement your logic.</p>
132
+ </div></div>
133
+
134
+ <div id="footer">
135
+ Generated on Fri Nov 21 00:28:16 2025 by
136
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
137
+ 0.9.37 (ruby-3.4.4).
138
+ </div>
139
+
140
+ </div>
141
+ </body>
142
+ </html>
data/docs/yard/file.rails_integration.html ADDED
@@ -0,0 +1,160 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>
7
+ File: Integration / Rails Integration
8
+
9
+ &mdash; Servus | Service Object Framework
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" />
16
+
17
+ <script type="text/javascript">
18
+ pathId = "rails_integration";
19
+ relpath = '';
20
+ </script>
21
+
22
+
23
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
24
+
25
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
26
+
27
+
28
+ </head>
29
+ <body>
30
+ <div class="nav_wrap">
31
+ <iframe id="nav" src="file_list.html?1"></iframe>
32
+ <div id="resizer"></div>
33
+ </div>
34
+
35
+ <div id="main" tabindex="-1">
36
+ <div id="header">
37
+ <div id="menu">
38
+
39
+ <a href="_index.html">Index</a> &raquo;
40
+ <span class="title">File: Integration / Rails Integration</span>
41
+
42
+ </div>
43
+
44
+ <div id="search">
45
+
46
+ <a class="full_list_link" id="class_list_link"
47
+ href="class_list.html">
48
+
49
+ <svg width="24" height="24">
50
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
51
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
52
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
53
+ </svg>
54
+ </a>
55
+
56
+ </div>
57
+ <div class="clear"></div>
58
+ </div>
59
+
60
+ <div id="content"><div id='filecontents'><h1 id="rails-integration">Rails Integration</h1>
61
+
62
+ <p>Servus core works in any Ruby application. Rails-specific features (async, controller helpers, generators) are optional additions that integrate with Rails conventions.</p>
63
+
64
+ <h2 id="controller-integration">Controller Integration</h2>
65
+
66
+ <p>Use the <code>run_service</code> helper to call services from controllers with automatic error handling:</p>
67
+
68
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>UsersController</span> <span class='op'>&lt;</span> <span class='const'>ApplicationController</span>
69
+ <span class='id identifier rubyid_include'>include</span> <span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Helpers.html" title="Servus::Helpers (module)">Helpers</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Helpers/ControllerHelpers.html" title="Servus::Helpers::ControllerHelpers (module)">ControllerHelpers</a></span></span>
70
+
71
+ <span class='kw'>def</span> <span class='id identifier rubyid_create'>create</span>
72
+ <span class='id identifier rubyid_run_service'>run_service</span><span class='lparen'>(</span><span class='const'>Users</span><span class='op'>::</span><span class='const'>Create</span><span class='op'>::</span><span class='const'>Service</span><span class='comma'>,</span> <span class='id identifier rubyid_user_params'>user_params</span><span class='rparen'>)</span>
73
+ <span class='kw'>end</span>
74
+
75
+ <span class='comment'># Failures automatically render JSON:
76
+ </span> <span class='comment'># { &quot;error&quot;: { &quot;code&quot;: &quot;validation_error&quot;, &quot;message&quot;: &quot;...&quot; } }
77
+ </span> <span class='comment'># with appropriate HTTP status code
78
+ </span> <span class='comment'>#
79
+ </span> <span class='comment'># Success will go to view and service result will be available on @result
80
+ </span><span class='kw'>end</span>
81
+ </code></pre>
82
+
83
+ <p>Without the helper, handle responses manually:</p>
84
+
85
+ <pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_create'>create</span>
86
+ <span class='id identifier rubyid_result'>result</span> <span class='op'>=</span> <span class='const'>Users</span><span class='op'>::</span><span class='const'>Create</span><span class='op'>::</span><span class='const'>Service</span><span class='period'>.</span><span class='id identifier rubyid_call'>call</span><span class='lparen'>(</span><span class='id identifier rubyid_user_params'>user_params</span><span class='rparen'>)</span>
87
+ <span class='kw'>if</span> <span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span>
88
+ <span class='id identifier rubyid_render'>render</span> <span class='label'>json:</span> <span class='lbrace'>{</span> <span class='label'>user:</span> <span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_data'>data</span><span class='lbracket'>[</span><span class='symbol'>:user</span><span class='rbracket'>]</span> <span class='rbrace'>}</span><span class='comma'>,</span> <span class='label'>status:</span> <span class='symbol'>:created</span>
89
+ <span class='kw'>else</span>
90
+ <span class='id identifier rubyid_render'>render</span> <span class='label'>json:</span> <span class='lbrace'>{</span> <span class='label'>error:</span> <span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_error'>error</span><span class='period'>.</span><span class='id identifier rubyid_api_error'>api_error</span> <span class='rbrace'>}</span><span class='comma'>,</span> <span class='label'>status:</span> <span class='id identifier rubyid_error_status'>error_status</span><span class='lparen'>(</span><span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_error'>error</span><span class='rparen'>)</span>
91
+ <span class='kw'>end</span>
92
+ <span class='kw'>end</span>
93
+ </code></pre>
94
+
95
+ <h2 id="generator">Generator</h2>
96
+
97
+ <p>Generate services with specs and schema files:</p>
98
+
99
+ <pre class="code bash"><code class="bash">rails generate servus:service process_payment
100
+
101
+ # Creates:
102
+ # app/services/process_payment/service.rb
103
+ # spec/services/process_payment/service_spec.rb
104
+ # app/schemas/services/process_payment/arguments.json
105
+ # app/schemas/services/process_payment/result.json
106
+ </code></pre>
107
+
108
+ <p>Schema files are optional - delete them if you don&#39;t need validation.</p>
109
+
110
+ <h2 id="autoloading">Autoloading</h2>
111
+
112
+ <p>Servus follows Rails autoloading conventions. Services in <code>app/services/</code> are automatically loaded by Rails:</p>
113
+
114
+ <pre class="code ruby"><code class="ruby"><span class='comment'># app/services/users/create/service.rb
115
+ </span><span class='kw'>module</span> <span class='const'>Users</span>
116
+ <span class='kw'>module</span> <span class='const'>Create</span>
117
+ <span class='kw'>class</span> <span class='const'>Service</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Base.html" title="Servus::Base (class)">Base</a></span></span>
118
+ <span class='comment'># ...
119
+ </span> <span class='kw'>end</span>
120
+ <span class='kw'>end</span>
121
+ <span class='kw'>end</span>
122
+
123
+ <span class='comment'># Rails autoloads this as Users::Create::Service
124
+ </span></code></pre>
125
+
126
+ <h2 id="configuration">Configuration</h2>
127
+
128
+ <p>Configure Servus in an initializer if needed:</p>
129
+
130
+ <pre class="code ruby"><code class="ruby"><span class='comment'># config/initializers/servus.rb
131
+ </span><span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Servus.html#configure-class_method" title="Servus.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
132
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_schema_root'>schema_root</span> <span class='op'>=</span> <span class='const'>Rails</span><span class='period'>.</span><span class='id identifier rubyid_root'>root</span><span class='period'>.</span><span class='id identifier rubyid_join'>join</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>config/schemas</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
133
+ <span class='kw'>end</span>
134
+ </code></pre>
135
+
136
+ <p>Most applications don&#39;t need any configuration.</p>
137
+
138
+ <h2 id="background-jobs">Background Jobs</h2>
139
+
140
+ <p>Async execution requires ActiveJob setup. Configure your adapter:</p>
141
+
142
+ <pre class="code ruby"><code class="ruby"><span class='comment'># config/application.rb
143
+ </span><span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_active_job'>active_job</span><span class='period'>.</span><span class='id identifier rubyid_queue_adapter'>queue_adapter</span> <span class='op'>=</span> <span class='symbol'>:sidekiq</span>
144
+ </code></pre>
145
+
146
+ <p>Then use <code>.call_async</code>:</p>
147
+
148
+ <pre class="code ruby"><code class="ruby"><span class='const'>Users</span><span class='op'>::</span><span class='const'>SendWelcomeEmail</span><span class='op'>::</span><span class='const'>Service</span><span class='period'>.</span><span class='id identifier rubyid_call_async'>call_async</span><span class='lparen'>(</span><span class='label'>user_id:</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_id'>id</span><span class='rparen'>)</span>
149
+ </code></pre>
150
+ </div></div>
151
+
152
+ <div id="footer">
153
+ Generated on Fri Nov 21 00:30:04 2025 by
154
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
155
+ 0.9.37 (ruby-3.4.4).
156
+ </div>
157
+
158
+ </div>
159
+ </body>
160
+ </html>
data/docs/yard/file.schema_validation.html ADDED
@@ -0,0 +1,188 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>
7
+ File: Features / Schema Validation
8
+
9
+ &mdash; Servus | Service Object Framework
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" />
16
+
17
+ <script type="text/javascript">
18
+ pathId = "schema_validation";
19
+ relpath = '';
20
+ </script>
21
+
22
+
23
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
24
+
25
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
26
+
27
+
28
+ </head>
29
+ <body>
30
+ <div class="nav_wrap">
31
+ <iframe id="nav" src="file_list.html?1"></iframe>
32
+ <div id="resizer"></div>
33
+ </div>
34
+
35
+ <div id="main" tabindex="-1">
36
+ <div id="header">
37
+ <div id="menu">
38
+
39
+ <a href="_index.html">Index</a> &raquo;
40
+ <span class="title">File: Features / Schema Validation</span>
41
+
42
+ </div>
43
+
44
+ <div id="search">
45
+
46
+ <a class="full_list_link" id="class_list_link"
47
+ href="class_list.html">
48
+
49
+ <svg width="24" height="24">
50
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
51
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
52
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
53
+ </svg>
54
+ </a>
55
+
56
+ </div>
57
+ <div class="clear"></div>
58
+ </div>
59
+
60
+ <div id="content"><div id='filecontents'><h1 id="schema-validation">Schema Validation</h1>
61
+
62
+ <p>Servus provides optional JSON Schema validation for service arguments and results. Validation is opt-in - services work fine without schemas.</p>
63
+
64
+ <h2 id="how-it-works">How It Works</h2>
65
+
66
+ <p>Define schemas using the <code>schema</code> DSL method (recommended) or as constants. The framework validates arguments before execution and results after execution. Invalid data raises <code>ValidationError</code>.</p>
67
+
68
+ <h3 id="preferred-schema-dsl-method">Preferred: Schema DSL Method</h3>
69
+
70
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>ProcessPayment</span><span class='op'>::</span><span class='const'>Service</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Base.html" title="Servus::Base (class)">Base</a></span></span>
71
+ <span class='id identifier rubyid_schema'>schema</span><span class='lparen'>(</span>
72
+ <span class='label'>arguments:</span> <span class='lbrace'>{</span>
73
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>object</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
74
+ <span class='label'>required:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>user_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>amount</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
75
+ <span class='label'>properties:</span> <span class='lbrace'>{</span>
76
+ <span class='label'>user_id:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>integer</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>example:</span> <span class='int'>123</span> <span class='rbrace'>}</span><span class='comma'>,</span>
77
+ <span class='label'>amount:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>number</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>minimum:</span> <span class='float'>0.01</span><span class='comma'>,</span> <span class='label'>example:</span> <span class='float'>100.0</span> <span class='rbrace'>}</span>
78
+ <span class='rbrace'>}</span>
79
+ <span class='rbrace'>}</span><span class='comma'>,</span>
80
+ <span class='label'>result:</span> <span class='lbrace'>{</span>
81
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>object</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
82
+ <span class='label'>required:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>transaction_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>new_balance</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
83
+ <span class='label'>properties:</span> <span class='lbrace'>{</span>
84
+ <span class='label'>transaction_id:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>string</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>example:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>txn_abc123</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
85
+ <span class='label'>new_balance:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>number</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>example:</span> <span class='float'>950.0</span> <span class='rbrace'>}</span>
86
+ <span class='rbrace'>}</span>
87
+ <span class='rbrace'>}</span>
88
+ <span class='rparen'>)</span>
89
+ <span class='kw'>end</span>
90
+ </code></pre>
91
+
92
+ <p><strong>Pro tip:</strong> Add <code>example</code> or <code>examples</code> keywords to your schemas. These values can be automatically extracted in tests using <code>servus_arguments_example()</code> and <code>servus_result_example()</code> helpers. See the <a href="../integration/testing.md#schema-example-helpers">Testing documentation</a> for details.</p>
93
+
94
+ <p>You can define just one schema if needed:</p>
95
+
96
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>SendEmail</span><span class='op'>::</span><span class='const'>Service</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Base.html" title="Servus::Base (class)">Base</a></span></span>
97
+ <span class='id identifier rubyid_schema'>schema</span> <span class='label'>arguments:</span> <span class='lbrace'>{</span>
98
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>object</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
99
+ <span class='label'>required:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>email</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>subject</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
100
+ <span class='label'>properties:</span> <span class='lbrace'>{</span>
101
+ <span class='label'>email:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>string</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>email</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
102
+ <span class='label'>subject:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>string</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span>
103
+ <span class='rbrace'>}</span>
104
+ <span class='rbrace'>}</span>
105
+ <span class='kw'>end</span>
106
+ </code></pre>
107
+
108
+ <h3 id="alternative-inline-constants">Alternative: Inline Constants</h3>
109
+
110
+ <p>Constants are still supported for backwards compatibility:</p>
111
+
112
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>ProcessPayment</span><span class='op'>::</span><span class='const'>Service</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Base.html" title="Servus::Base (class)">Base</a></span></span>
113
+ <span class='const'>ARGUMENTS_SCHEMA</span> <span class='op'>=</span> <span class='lbrace'>{</span>
114
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>object</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
115
+ <span class='label'>required:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>user_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>amount</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
116
+ <span class='label'>properties:</span> <span class='lbrace'>{</span>
117
+ <span class='label'>user_id:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>integer</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
118
+ <span class='label'>amount:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>number</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>minimum:</span> <span class='float'>0.01</span> <span class='rbrace'>}</span>
119
+ <span class='rbrace'>}</span>
120
+ <span class='rbrace'>}</span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span>
121
+
122
+ <span class='const'>RESULT_SCHEMA</span> <span class='op'>=</span> <span class='lbrace'>{</span>
123
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>object</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
124
+ <span class='label'>required:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>transaction_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>new_balance</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
125
+ <span class='label'>properties:</span> <span class='lbrace'>{</span>
126
+ <span class='label'>transaction_id:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>string</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
127
+ <span class='label'>new_balance:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>number</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span>
128
+ <span class='rbrace'>}</span>
129
+ <span class='rbrace'>}</span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span>
130
+ <span class='kw'>end</span>
131
+ </code></pre>
132
+
133
+ <h2 id="file-based-schemas">File-Based Schemas</h2>
134
+
135
+ <p>For complex schemas, use JSON files instead of inline definitions. Create files at:</p>
136
+
137
+ <ul>
138
+ <li><code>app/schemas/services/service_name/arguments.json</code></li>
139
+ <li><code>app/schemas/services/service_name/result.json</code></li>
140
+ </ul>
141
+
142
+ <h3 id="schema-lookup-precedence">Schema Lookup Precedence</h3>
143
+
144
+ <p>Servus checks for schemas in this order:</p>
145
+
146
+ <ol>
147
+ <li><strong>schema DSL method</strong> (if defined)</li>
148
+ <li><strong>Inline constants</strong> (ARGUMENTS_SCHEMA, RESULT_SCHEMA)</li>
149
+ <li><strong>JSON files</strong> (in schema_root directory)</li>
150
+ </ol>
151
+
152
+ <p>Schemas are cached after first load for performance.</p>
153
+
154
+ <h2 id="three-layers-of-validation">Three Layers of Validation</h2>
155
+
156
+ <p><strong>Schema Validation</strong> (Servus): Type safety and structure at service boundaries</p>
157
+
158
+ <p><strong>Business Rules</strong> (Service Logic): Domain-specific constraints during execution</p>
159
+
160
+ <p><strong>Model Validation</strong> (ActiveRecord): Database constraints before persistence</p>
161
+
162
+ <p>Each layer has a different purpose - don&#39;t duplicate validation across layers.</p>
163
+
164
+ <h2 id="configuration">Configuration</h2>
165
+
166
+ <p>Change the schema file location if needed:</p>
167
+
168
+ <pre class="code ruby"><code class="ruby"><span class='comment'># config/initializers/servus.rb
169
+ </span><span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Servus.html#configure-class_method" title="Servus.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
170
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_schema_root'>schema_root</span> <span class='op'>=</span> <span class='const'>Rails</span><span class='period'>.</span><span class='id identifier rubyid_root'>root</span><span class='period'>.</span><span class='id identifier rubyid_join'>join</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>config/schemas</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
171
+ <span class='kw'>end</span>
172
+ </code></pre>
173
+
174
+ <p>Clear the schema cache during development when schemas change:</p>
175
+
176
+ <pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Support.html" title="Servus::Support (module)">Support</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Support/Validator.html" title="Servus::Support::Validator (class)">Validator</a></span></span><span class='period'>.</span><span class='id identifier rubyid_clear_cache!'><span class='object_link'><a href="Servus/Support/Validator.html#clear_cache!-class_method" title="Servus::Support::Validator.clear_cache! (method)">clear_cache!</a></span></span>
177
+ </code></pre>
178
+ </div></div>
179
+
180
+ <div id="footer">
181
+ Generated on Fri Nov 21 00:30:04 2025 by
182
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
183
+ 0.9.37 (ruby-3.4.4).
184
+ </div>
185
+
186
+ </div>
187
+ </body>
188
+ </html>