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.1_common_patterns.html ADDED
@@ -0,0 +1,154 @@
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: Guides / 1. Common Patterns
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 = "1_common_patterns";
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: Guides / 1. Common Patterns</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="common-patterns">Common Patterns</h1>
61
+
62
+ <p>Common architectural patterns for using Servus effectively.</p>
63
+
64
+ <h2 id="parent-child-services">Parent-Child Services</h2>
65
+
66
+ <p>When one service orchestrates multiple sub-operations, decide on transaction boundaries and error propagation.</p>
67
+
68
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>Orders</span><span class='op'>::</span><span class='const'>Checkout</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>
69
+ <span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
70
+ <span class='const'>ActiveRecord</span><span class='op'>::</span><span class='const'>Base</span><span class='period'>.</span><span class='id identifier rubyid_transaction'>transaction</span> <span class='kw'>do</span>
71
+ <span class='comment'># Create order
72
+ </span> <span class='id identifier rubyid_order_result'>order_result</span> <span class='op'>=</span> <span class='const'>Orders</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_order_params'>order_params</span><span class='rparen'>)</span>
73
+ <span class='kw'>return</span> <span class='id identifier rubyid_order_result'>order_result</span> <span class='kw'>unless</span> <span class='id identifier rubyid_order_result'>order_result</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span>
74
+
75
+ <span class='comment'># Charge payment
76
+ </span> <span class='id identifier rubyid_payment_result'>payment_result</span> <span class='op'>=</span> <span class='const'>Payments</span><span class='op'>::</span><span class='const'>Charge</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>
77
+ <span class='label'>user_id:</span> <span class='ivar'>@user_id</span><span class='comma'>,</span>
78
+ <span class='label'>amount:</span> <span class='id identifier rubyid_order_result'>order_result</span><span class='period'>.</span><span class='id identifier rubyid_data'>data</span><span class='lbracket'>[</span><span class='symbol'>:order</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_total'>total</span>
79
+ <span class='rparen'>)</span>
80
+ <span class='kw'>return</span> <span class='id identifier rubyid_payment_result'>payment_result</span> <span class='kw'>unless</span> <span class='id identifier rubyid_payment_result'>payment_result</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span>
81
+
82
+ <span class='comment'># Update inventory
83
+ </span> <span class='id identifier rubyid_inventory_result'>inventory_result</span> <span class='op'>=</span> <span class='const'>Inventory</span><span class='op'>::</span><span class='const'>Reserve</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>
84
+ <span class='label'>order_id:</span> <span class='id identifier rubyid_order_result'>order_result</span><span class='period'>.</span><span class='id identifier rubyid_data'>data</span><span class='lbracket'>[</span><span class='symbol'>:order</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_id'>id</span>
85
+ <span class='rparen'>)</span>
86
+ <span class='kw'>return</span> <span class='id identifier rubyid_inventory_result'>inventory_result</span> <span class='kw'>unless</span> <span class='id identifier rubyid_inventory_result'>inventory_result</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span>
87
+
88
+ <span class='id identifier rubyid_success'>success</span><span class='lparen'>(</span><span class='label'>order:</span> <span class='id identifier rubyid_order_result'>order_result</span><span class='period'>.</span><span class='id identifier rubyid_data'>data</span><span class='lbracket'>[</span><span class='symbol'>:order</span><span class='rbracket'>]</span><span class='rparen'>)</span>
89
+ <span class='kw'>end</span>
90
+ <span class='kw'>end</span>
91
+ <span class='kw'>end</span>
92
+ </code></pre>
93
+
94
+ <p><strong>Use parent transaction when</strong>: All children must succeed or all roll back (atomic operation)</p>
95
+
96
+ <p><strong>Use child transactions when</strong>: Children can succeed independently (partial success acceptable)</p>
97
+
98
+ <h2 id="async-with-result-persistence">Async with Result Persistence</h2>
99
+
100
+ <p>Store async results in database for later retrieval:</p>
101
+
102
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Controller creates placeholder
103
+ </span><span class='id identifier rubyid_report'>report</span> <span class='op'>=</span> <span class='const'>Report</span><span class='period'>.</span><span class='id identifier rubyid_create!'>create!</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='comma'>,</span> <span class='label'>status:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>pending</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
104
+ <span class='const'>GenerateReport</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'>report_id:</span> <span class='id identifier rubyid_report'>report</span><span class='period'>.</span><span class='id identifier rubyid_id'>id</span><span class='rparen'>)</span>
105
+
106
+ <span class='comment'># Service updates record
107
+ </span><span class='kw'>class</span> <span class='const'>GenerateReport</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>
108
+ <span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
109
+ <span class='id identifier rubyid_report'>report</span> <span class='op'>=</span> <span class='const'>Report</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='ivar'>@report_id</span><span class='rparen'>)</span>
110
+ <span class='id identifier rubyid_data'>data</span> <span class='op'>=</span> <span class='id identifier rubyid_generate_report_data'>generate_report_data</span>
111
+
112
+ <span class='id identifier rubyid_report'>report</span><span class='period'>.</span><span class='id identifier rubyid_update!'>update!</span><span class='lparen'>(</span><span class='label'>data:</span> <span class='id identifier rubyid_data'>data</span><span class='comma'>,</span> <span class='label'>status:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>completed</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
113
+ <span class='id identifier rubyid_success'>success</span><span class='lparen'>(</span><span class='label'>report:</span> <span class='id identifier rubyid_report'>report</span><span class='rparen'>)</span>
114
+ <span class='kw'>end</span>
115
+ <span class='kw'>end</span>
116
+ </code></pre>
117
+
118
+ <h2 id="idempotent-services">Idempotent Services</h2>
119
+
120
+ <p>Use database constraints to make services idempotent:</p>
121
+
122
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</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='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>
123
+ <span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
124
+ <span class='comment'># Unique constraint on email prevents duplicates
125
+ </span> <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_create!'>create!</span><span class='lparen'>(</span><span class='label'>email:</span> <span class='ivar'>@email</span><span class='comma'>,</span> <span class='label'>name:</span> <span class='ivar'>@name</span><span class='rparen'>)</span>
126
+ <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='rparen'>)</span>
127
+ <span class='kw'>rescue</span> <span class='const'>ActiveRecord</span><span class='op'>::</span><span class='const'>RecordNotUnique</span>
128
+ <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_by!'>find_by!</span><span class='lparen'>(</span><span class='label'>email:</span> <span class='ivar'>@email</span><span class='rparen'>)</span>
129
+ <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='rparen'>)</span> <span class='comment'># Return existing user, not error
130
+ </span> <span class='kw'>end</span>
131
+ <span class='kw'>end</span>
132
+ </code></pre>
133
+
134
+ <p>Or check for existing resources explicitly:</p>
135
+
136
+ <pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
137
+ <span class='id identifier rubyid_existing'>existing</span> <span class='op'>=</span> <span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_find_by'>find_by</span><span class='lparen'>(</span><span class='label'>email:</span> <span class='ivar'>@email</span><span class='rparen'>)</span>
138
+ <span class='kw'>return</span> <span class='id identifier rubyid_success'>success</span><span class='lparen'>(</span><span class='label'>user:</span> <span class='id identifier rubyid_existing'>existing</span><span class='rparen'>)</span> <span class='kw'>if</span> <span class='id identifier rubyid_existing'>existing</span>
139
+
140
+ <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_create!'>create!</span><span class='lparen'>(</span><span class='label'>email:</span> <span class='ivar'>@email</span><span class='comma'>,</span> <span class='label'>name:</span> <span class='ivar'>@name</span><span class='rparen'>)</span>
141
+ <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='rparen'>)</span>
142
+ <span class='kw'>end</span>
143
+ </code></pre>
144
+ </div></div>
145
+
146
+ <div id="footer">
147
+ Generated on Fri Nov 21 00:33:23 2025 by
148
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
149
+ 0.9.37 (ruby-3.4.4).
150
+ </div>
151
+
152
+ </div>
153
+ </body>
154
+ </html>
data/docs/yard/file.1_configuration.html ADDED
@@ -0,0 +1,115 @@
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 / 1. Configuration
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 = "1_configuration";
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 / 1. Configuration</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="configuration">Configuration</h1>
61
+
62
+ <p>Servus works without configuration. One optional setting exists for schema file location.</p>
63
+
64
+ <h2 id="schema-root">Schema Root</h2>
65
+
66
+ <p>By default, Servus looks for schema JSON files in <code>Rails.root/app/schemas/services</code> (or <code>./app/schemas/services</code> in non-Rails apps).</p>
67
+
68
+ <p>Change the location if needed:</p>
69
+
70
+ <pre class="code ruby"><code class="ruby"><span class='comment'># config/initializers/servus.rb
71
+ </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>
72
+ <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>
73
+ <span class='kw'>end</span>
74
+ </code></pre>
75
+
76
+ <p>This affects legacy file-based schemas only - schemas defined via the <code>schema</code> DSL method do not use files.</p>
77
+
78
+ <h2 id="schema-cache">Schema Cache</h2>
79
+
80
+ <p>Schemas are cached after first load for performance. Clear the cache during development when schemas change:</p>
81
+
82
+ <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>
83
+ </code></pre>
84
+
85
+ <p>In production, schemas are deployed with code - no need to clear cache.</p>
86
+
87
+ <h2 id="log-level">Log Level</h2>
88
+
89
+ <p>Servus uses <code>Rails.logger</code> (or stdout in non-Rails apps). Control logging via Rails configuration:</p>
90
+
91
+ <pre class="code ruby"><code class="ruby"><span class='comment'># config/environments/production.rb
92
+ </span><span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_log_level'>log_level</span> <span class='op'>=</span> <span class='symbol'>:info</span> <span class='comment'># Hides DEBUG argument logs
93
+ </span></code></pre>
94
+
95
+ <h2 id="activejob-configuration">ActiveJob Configuration</h2>
96
+
97
+ <p>Async execution uses ActiveJob. Configure your adapter:</p>
98
+
99
+ <pre class="code ruby"><code class="ruby"><span class='comment'># config/application.rb
100
+ </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>
101
+ <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_default_queue_name'>default_queue_name</span> <span class='op'>=</span> <span class='symbol'>:default</span>
102
+ </code></pre>
103
+
104
+ <p>Servus respects ActiveJob queue configuration - no Servus-specific setup needed.</p>
105
+ </div></div>
106
+
107
+ <div id="footer">
108
+ Generated on Fri Nov 21 00:33:23 2025 by
109
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
110
+ 0.9.37 (ruby-3.4.4).
111
+ </div>
112
+
113
+ </div>
114
+ </body>
115
+ </html>
data/docs/yard/file.1_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 / 1. 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 = "1_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 / 1. 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:33:23 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>