servus 0.1.3 → 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 (116) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +6 -0
  3. data/CHANGELOG.md +7 -0
  4. data/IDEAS.md +5 -0
  5. data/READme.md +147 -42
  6. data/Rakefile +33 -0
  7. data/builds/servus-0.1.3.gem +0 -0
  8. data/builds/servus-0.1.4.gem +0 -0
  9. data/docs/core/1_overview.md +77 -0
  10. data/docs/core/2_architecture.md +92 -0
  11. data/docs/core/3_service_objects.md +121 -0
  12. data/docs/features/1_schema_validation.md +119 -0
  13. data/docs/features/2_error_handling.md +121 -0
  14. data/docs/features/3_async_execution.md +81 -0
  15. data/docs/features/4_logging.md +64 -0
  16. data/docs/guides/1_common_patterns.md +90 -0
  17. data/docs/guides/2_migration_guide.md +175 -0
  18. data/docs/integration/1_configuration.md +51 -0
  19. data/docs/integration/2_testing.md +164 -0
  20. data/docs/integration/3_rails_integration.md +99 -0
  21. data/docs/yard/Servus/Base.html +1645 -0
  22. data/docs/yard/Servus/Config.html +582 -0
  23. data/docs/yard/Servus/Extensions/Async/Call.html +400 -0
  24. data/docs/yard/Servus/Extensions/Async/Errors/AsyncError.html +140 -0
  25. data/docs/yard/Servus/Extensions/Async/Errors/JobEnqueueError.html +154 -0
  26. data/docs/yard/Servus/Extensions/Async/Errors/ServiceNotFoundError.html +154 -0
  27. data/docs/yard/Servus/Extensions/Async/Errors.html +128 -0
  28. data/docs/yard/Servus/Extensions/Async/Ext.html +119 -0
  29. data/docs/yard/Servus/Extensions/Async/Job.html +310 -0
  30. data/docs/yard/Servus/Extensions/Async.html +141 -0
  31. data/docs/yard/Servus/Extensions.html +117 -0
  32. data/docs/yard/Servus/Generators/ServiceGenerator.html +261 -0
  33. data/docs/yard/Servus/Generators.html +115 -0
  34. data/docs/yard/Servus/Helpers/ControllerHelpers.html +457 -0
  35. data/docs/yard/Servus/Helpers.html +115 -0
  36. data/docs/yard/Servus/Railtie.html +134 -0
  37. data/docs/yard/Servus/Support/Errors/AuthenticationError.html +287 -0
  38. data/docs/yard/Servus/Support/Errors/BadRequestError.html +283 -0
  39. data/docs/yard/Servus/Support/Errors/ForbiddenError.html +284 -0
  40. data/docs/yard/Servus/Support/Errors/InternalServerError.html +283 -0
  41. data/docs/yard/Servus/Support/Errors/NotFoundError.html +284 -0
  42. data/docs/yard/Servus/Support/Errors/ServiceError.html +489 -0
  43. data/docs/yard/Servus/Support/Errors/ServiceUnavailableError.html +290 -0
  44. data/docs/yard/Servus/Support/Errors/UnauthorizedError.html +200 -0
  45. data/docs/yard/Servus/Support/Errors/UnprocessableEntityError.html +288 -0
  46. data/docs/yard/Servus/Support/Errors/ValidationError.html +200 -0
  47. data/docs/yard/Servus/Support/Errors.html +140 -0
  48. data/docs/yard/Servus/Support/Logger.html +856 -0
  49. data/docs/yard/Servus/Support/Rescuer/BlockContext.html +585 -0
  50. data/docs/yard/Servus/Support/Rescuer/CallOverride.html +257 -0
  51. data/docs/yard/Servus/Support/Rescuer/ClassMethods.html +343 -0
  52. data/docs/yard/Servus/Support/Rescuer.html +267 -0
  53. data/docs/yard/Servus/Support/Response.html +574 -0
  54. data/docs/yard/Servus/Support/Validator.html +1150 -0
  55. data/docs/yard/Servus/Support.html +119 -0
  56. data/docs/yard/Servus/Testing/ExampleBuilders.html +523 -0
  57. data/docs/yard/Servus/Testing/ExampleExtractor.html +578 -0
  58. data/docs/yard/Servus/Testing.html +142 -0
  59. data/docs/yard/Servus.html +343 -0
  60. data/docs/yard/_index.html +535 -0
  61. data/docs/yard/class_list.html +54 -0
  62. data/docs/yard/css/common.css +1 -0
  63. data/docs/yard/css/full_list.css +58 -0
  64. data/docs/yard/css/style.css +503 -0
  65. data/docs/yard/file.1_common_patterns.html +154 -0
  66. data/docs/yard/file.1_configuration.html +115 -0
  67. data/docs/yard/file.1_overview.html +142 -0
  68. data/docs/yard/file.1_schema_validation.html +188 -0
  69. data/docs/yard/file.2_architecture.html +157 -0
  70. data/docs/yard/file.2_error_handling.html +190 -0
  71. data/docs/yard/file.2_migration_guide.html +242 -0
  72. data/docs/yard/file.2_testing.html +227 -0
  73. data/docs/yard/file.3_async_execution.html +145 -0
  74. data/docs/yard/file.3_rails_integration.html +160 -0
  75. data/docs/yard/file.3_service_objects.html +191 -0
  76. data/docs/yard/file.4_logging.html +135 -0
  77. data/docs/yard/file.ErrorHandling.html +190 -0
  78. data/docs/yard/file.READme.html +674 -0
  79. data/docs/yard/file.architecture.html +157 -0
  80. data/docs/yard/file.async_execution.html +145 -0
  81. data/docs/yard/file.common_patterns.html +154 -0
  82. data/docs/yard/file.configuration.html +115 -0
  83. data/docs/yard/file.error_handling.html +190 -0
  84. data/docs/yard/file.logging.html +135 -0
  85. data/docs/yard/file.migration_guide.html +242 -0
  86. data/docs/yard/file.overview.html +142 -0
  87. data/docs/yard/file.rails_integration.html +160 -0
  88. data/docs/yard/file.schema_validation.html +188 -0
  89. data/docs/yard/file.service_objects.html +191 -0
  90. data/docs/yard/file.testing.html +227 -0
  91. data/docs/yard/file_list.html +119 -0
  92. data/docs/yard/frames.html +22 -0
  93. data/docs/yard/index.html +674 -0
  94. data/docs/yard/js/app.js +344 -0
  95. data/docs/yard/js/full_list.js +242 -0
  96. data/docs/yard/js/jquery.js +4 -0
  97. data/docs/yard/method_list.html +542 -0
  98. data/docs/yard/top-level-namespace.html +110 -0
  99. data/lib/generators/servus/service/service_generator.rb +64 -1
  100. data/lib/generators/servus/service/templates/service.rb.erb +1 -1
  101. data/lib/servus/base.rb +258 -57
  102. data/lib/servus/config.rb +58 -12
  103. data/lib/servus/extensions/async/call.rb +50 -18
  104. data/lib/servus/extensions/async/errors.rb +23 -3
  105. data/lib/servus/extensions/async/ext.rb +10 -2
  106. data/lib/servus/extensions/async/job.rb +30 -9
  107. data/lib/servus/helpers/controller_helpers.rb +73 -37
  108. data/lib/servus/support/errors.rb +135 -45
  109. data/lib/servus/support/rescuer.rb +189 -36
  110. data/lib/servus/support/response.rb +49 -7
  111. data/lib/servus/support/validator.rb +120 -19
  112. data/lib/servus/testing/example_builders.rb +133 -0
  113. data/lib/servus/testing/example_extractor.rb +309 -0
  114. data/lib/servus/testing.rb +17 -0
  115. data/lib/servus/version.rb +1 -1
  116. metadata +117 -19
data/docs/yard/file.3_async_execution.html ADDED
@@ -0,0 +1,145 @@
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 / 3. Async Execution
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 = "3_async_execution";
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 / 3. Async Execution</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="async-execution">Async Execution</h1>
61
+
62
+ <p>Servus provides asynchronous execution via ActiveJob. Services run identically whether called sync or async - they&#39;re unaware of execution context.</p>
63
+
64
+ <h2 id="usage">Usage</h2>
65
+
66
+ <p>Call <code>.call_async(**args)</code> instead of <code>.call(**args)</code> to execute in the background. The service is enqueued immediately and executed by a worker.</p>
67
+
68
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Synchronous
69
+ </span><span class='id identifier rubyid_result'>result</span> <span class='op'>=</span> <span class='const'>ProcessReport</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='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'>report_type:</span> <span class='symbol'>:monthly</span><span class='rparen'>)</span>
70
+ <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'>:report</span><span class='rbracket'>]</span> <span class='comment'># Available immediately
71
+ </span>
72
+ <span class='comment'># Asynchronous
73
+ </span><span class='const'>ProcessReport</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='comma'>,</span> <span class='label'>report_type:</span> <span class='symbol'>:monthly</span><span class='rparen'>)</span>
74
+ <span class='comment'># Returns true if enqueued successfully
75
+ </span><span class='comment'># Result not available (service hasn&#39;t run yet)
76
+ </span></code></pre>
77
+
78
+ <p>Services must accept JSON-serializable arguments for async execution (primitives, hashes, arrays, ActiveRecord objects via GlobalID). Complex objects like Procs won&#39;t work.</p>
79
+
80
+ <h2 id="queue-and-scheduling-options">Queue and Scheduling Options</h2>
81
+
82
+ <p>Pass ActiveJob options to control execution:</p>
83
+
84
+ <pre class="code ruby"><code class="ruby"><span class='const'>ProcessReport</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>
85
+ <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>
86
+ <span class='label'>queue:</span> <span class='symbol'>:critical</span><span class='comma'>,</span> <span class='comment'># Specify queue
87
+ </span> <span class='label'>priority:</span> <span class='int'>10</span><span class='comma'>,</span> <span class='comment'># Higher priority
88
+ </span> <span class='label'>wait:</span> <span class='int'>5</span><span class='period'>.</span><span class='id identifier rubyid_minutes'>minutes</span> <span class='comment'># Delay execution
89
+ </span><span class='rparen'>)</span>
90
+ </code></pre>
91
+
92
+ <h2 id="result-handling">Result Handling</h2>
93
+
94
+ <p>Async services can&#39;t return results to callers (the service hasn&#39;t executed yet). If you need results, implement persistence in the service:</p>
95
+
96
+ <pre class="code ruby"><code class="ruby"><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>
97
+ <span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
98
+ <span class='id identifier rubyid_report_data'>report_data</span> <span class='op'>=</span> <span class='id identifier rubyid_generate_report'>generate_report</span>
99
+
100
+ <span class='comment'># Persist result
101
+ </span> <span class='const'>Report</span><span class='period'>.</span><span class='id identifier rubyid_create!'>create!</span><span class='lparen'>(</span>
102
+ <span class='label'>user_id:</span> <span class='ivar'>@user_id</span><span class='comma'>,</span>
103
+ <span class='label'>data:</span> <span class='id identifier rubyid_report_data'>report_data</span><span class='comma'>,</span>
104
+ <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>
105
+ <span class='rparen'>)</span>
106
+
107
+ <span class='comment'># Optionally notify user
108
+ </span> <span class='const'>UserMailer</span><span class='period'>.</span><span class='id identifier rubyid_report_ready'>report_ready</span><span class='lparen'>(</span><span class='ivar'>@user_id</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_deliver_now'>deliver_now</span>
109
+
110
+ <span class='id identifier rubyid_success'>success</span><span class='lparen'>(</span><span class='label'>data:</span> <span class='id identifier rubyid_report_data'>report_data</span><span class='rparen'>)</span>
111
+ <span class='kw'>end</span>
112
+ <span class='kw'>end</span>
113
+
114
+ <span class='comment'># Controller creates placeholder, service updates it
115
+ </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>
116
+ <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'>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'>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>
117
+ </code></pre>
118
+
119
+ <h2 id="error-handling">Error Handling</h2>
120
+
121
+ <p>Failures (business logic) don&#39;t trigger retries - the job completes successfully but returns a failure Response.</p>
122
+
123
+ <p>Exceptions (system errors) trigger ActiveJob retry logic. Use <code>rescue_from</code> to convert transient errors into exceptions:</p>
124
+
125
+ <pre class="code ruby"><code class="ruby">class Service &lt; Servus::Base
126
+ rescue_from Net::HTTPError, Timeout::Error use: ServiceUnavailableError
127
+ end
128
+ </code></pre>
129
+
130
+ <h2 id="when-to-use-async">When to Use Async</h2>
131
+
132
+ <p><strong>Good candidates</strong>: Email sending, report generation, data imports, long-running API calls, cleanup tasks</p>
133
+
134
+ <p><strong>Poor candidates</strong>: Operations requiring immediate feedback, fast operations (&lt;100ms), critical path operations where user waits for result</p>
135
+ </div></div>
136
+
137
+ <div id="footer">
138
+ Generated on Fri Nov 21 00:33:23 2025 by
139
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
140
+ 0.9.37 (ruby-3.4.4).
141
+ </div>
142
+
143
+ </div>
144
+ </body>
145
+ </html>
data/docs/yard/file.3_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 / 3. 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 = "3_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 / 3. 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:33:23 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.3_service_objects.html ADDED
@@ -0,0 +1,191 @@
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 / 3. Service Objects
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 = "3_service_objects";
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 / 3. Service Objects</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="service-objects">Service Objects</h1>
61
+
62
+ <p>Service objects encapsulate one business operation into a testable, reusable class. They sit between controllers and models, handling orchestration logic that doesn&#39;t belong in either.</p>
63
+
64
+ <h2 id="the-pattern">The Pattern</h2>
65
+
66
+ <p>Services implement two methods: <code>initialize</code> (sets up dependencies) and <code>call</code> (executes business logic). All services return a <code>Response</code> object indicating success or failure.</p>
67
+
68
+ <pre class="code ruby"><code class="ruby"><span class='kw'>module</span> <span class='const'>Users</span>
69
+ <span class='kw'>module</span> <span class='const'>Create</span>
70
+ <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>
71
+ <span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='label'>email:</span><span class='comma'>,</span> <span class='label'>name:</span><span class='rparen'>)</span>
72
+ <span class='ivar'>@email</span> <span class='op'>=</span> <span class='id identifier rubyid_email'>email</span>
73
+ <span class='ivar'>@name</span> <span class='op'>=</span> <span class='id identifier rubyid_name'>name</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='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'>Email taken</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span> <span class='kw'>if</span> <span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_exists?'>exists?</span><span class='lparen'>(</span><span class='label'>email:</span> <span class='ivar'>@email</span><span class='rparen'>)</span>
78
+
79
+ <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>
80
+ <span class='id identifier rubyid_send_welcome_email'>send_welcome_email</span><span class='lparen'>(</span><span class='id identifier rubyid_user'>user</span><span class='rparen'>)</span>
81
+
82
+ <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>
83
+ <span class='kw'>end</span>
84
+ <span class='kw'>end</span>
85
+ <span class='kw'>end</span>
86
+ <span class='kw'>end</span>
87
+
88
+ <span class='comment'># Usage
89
+ </span><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='label'>email:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>user@example.com</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>John</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
90
+ <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
91
+ </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='comment'># =&gt; #&lt;User&gt;
92
+ </span></code></pre>
93
+
94
+ <h2 id="service-composition">Service Composition</h2>
95
+
96
+ <p>Services can call other services. Use the returned Response to decide whether to continue or propagate the failure.</p>
97
+
98
+ <pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
99
+ <span class='id identifier rubyid_user_result'>user_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>
100
+ <span class='kw'>return</span> <span class='id identifier rubyid_user_result'>user_result</span> <span class='kw'>unless</span> <span class='id identifier rubyid_user_result'>user_result</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span> <span class='comment'># propogates result failure
101
+ </span>
102
+ <span class='id identifier rubyid_account_result'>account_result</span> <span class='op'>=</span> <span class='const'>Accounts</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>
103
+ <span class='label'>user:</span> <span class='id identifier rubyid_user_result'>user_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='comma'>,</span>
104
+ <span class='label'>plan:</span> <span class='ivar'>@plan</span>
105
+ <span class='rparen'>)</span>
106
+ <span class='kw'>return</span> <span class='id identifier rubyid_account_result'>account_result</span> <span class='kw'>unless</span> <span class='id identifier rubyid_account_result'>account_result</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span> <span class='comment'># propogates result failure
107
+ </span>
108
+ <span class='id identifier rubyid_success'>success</span><span class='lparen'>(</span>
109
+ <span class='label'>user:</span> <span class='id identifier rubyid_user_result'>user_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='comma'>,</span>
110
+ <span class='label'>account:</span> <span class='id identifier rubyid_account_result'>account_result</span><span class='period'>.</span><span class='id identifier rubyid_data'>data</span><span class='lbracket'>[</span><span class='symbol'>:account</span><span class='rbracket'>]</span>
111
+ <span class='rparen'>)</span>
112
+ <span class='kw'>end</span>
113
+ </code></pre>
114
+
115
+ <h2 id="when-to-extract-to-services">When to Extract to Services</h2>
116
+
117
+ <p><strong>Extract when</strong>:</p>
118
+
119
+ <ul>
120
+ <li>Logic spans multiple models</li>
121
+ <li>Complex conditional branching</li>
122
+ <li>External API calls</li>
123
+ <li>Background processing needed</li>
124
+ <li>Testing requires extensive setup</li>
125
+ </ul>
126
+
127
+ <p><strong>Don&#39;t extract when</strong>:</p>
128
+
129
+ <ul>
130
+ <li>Simple CRUD operations</li>
131
+ <li>Single-model updates</li>
132
+ <li>Logic naturally belongs in model</li>
133
+ </ul>
134
+
135
+ <h2 id="directory-structure">Directory Structure</h2>
136
+
137
+ <p>Each service lives in its own namespace to avoid naming collisions and allow for support classes.</p>
138
+
139
+ <pre class="code ruby"><code class="ruby">app/services/
140
+ ├── users/
141
+ │ └── create/
142
+ │ ├── service.rb
143
+ │ └── support/
144
+ │ └── welcome_email.rb
145
+ └── orders/
146
+ └── process/
147
+ ├── service.rb
148
+ └── support/
149
+ ├── payment_gateway.rb
150
+ └── inventory_updater.rb
151
+ </code></pre>
152
+
153
+ <p>Support classes are private to their service - they should never be used by other services.</p>
154
+
155
+ <h2 id="testing">Testing</h2>
156
+
157
+ <p>Services are designed for easy testing with explicit inputs and outputs.</p>
158
+
159
+ <pre class="code ruby"><code class="ruby"><span class='const'>RSpec</span><span class='period'>.</span><span class='id identifier rubyid_describe'>describe</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='kw'>do</span>
160
+ <span class='id identifier rubyid_describe'>describe</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>.call</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>do</span>
161
+ <span class='id identifier rubyid_context'>context</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>with valid params</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>do</span>
162
+ <span class='id identifier rubyid_it'>it</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>creates user</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>do</span>
163
+ <span class='id identifier rubyid_result'>result</span> <span class='op'>=</span> <span class='id identifier rubyid_described_class'>described_class</span><span class='period'>.</span><span class='id identifier rubyid_call'>call</span><span class='lparen'>(</span><span class='label'>email:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>test@example.com</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Test</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
164
+ <span class='id identifier rubyid_expect'>expect</span><span class='lparen'>(</span><span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_to'>to</span> <span class='id identifier rubyid_be'>be</span> <span class='kw'>true</span>
165
+ <span class='id identifier rubyid_expect'>expect</span><span class='lparen'>(</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='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_to'>to</span> <span class='id identifier rubyid_be_persisted'>be_persisted</span>
166
+ <span class='kw'>end</span>
167
+ <span class='kw'>end</span>
168
+
169
+ <span class='id identifier rubyid_context'>context</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>with duplicate email</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>do</span>
170
+ <span class='id identifier rubyid_before'>before</span> <span class='lbrace'>{</span> <span class='id identifier rubyid_create'>create</span><span class='lparen'>(</span><span class='symbol'>:user</span><span class='comma'>,</span> <span class='label'>email:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>test@example.com</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span> <span class='rbrace'>}</span>
171
+
172
+ <span class='id identifier rubyid_it'>it</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>returns failure</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>do</span>
173
+ <span class='id identifier rubyid_result'>result</span> <span class='op'>=</span> <span class='id identifier rubyid_described_class'>described_class</span><span class='period'>.</span><span class='id identifier rubyid_call'>call</span><span class='lparen'>(</span><span class='label'>email:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>test@example.com</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Test</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
174
+ <span class='id identifier rubyid_expect'>expect</span><span class='lparen'>(</span><span class='id identifier rubyid_result'>result</span><span class='period'>.</span><span class='id identifier rubyid_success?'>success?</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_to'>to</span> <span class='id identifier rubyid_be'>be</span> <span class='kw'>false</span>
175
+ <span class='id identifier rubyid_expect'>expect</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='period'>.</span><span class='id identifier rubyid_message'>message</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_to'>to</span> <span class='id identifier rubyid_eq'>eq</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Email taken</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
176
+ <span class='kw'>end</span>
177
+ <span class='kw'>end</span>
178
+ <span class='kw'>end</span>
179
+ <span class='kw'>end</span>
180
+ </code></pre>
181
+ </div></div>
182
+
183
+ <div id="footer">
184
+ Generated on Fri Nov 21 00:33:23 2025 by
185
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
186
+ 0.9.37 (ruby-3.4.4).
187
+ </div>
188
+
189
+ </div>
190
+ </body>
191
+ </html>