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.
- checksums.yaml +4 -4
- data/.yardopts +6 -0
- data/CHANGELOG.md +8 -1
- data/IDEAS.md +5 -0
- data/READme.md +147 -42
- data/Rakefile +33 -0
- data/builds/servus-0.1.2.gem +0 -0
- data/builds/servus-0.1.3.gem +0 -0
- data/builds/servus-0.1.4.gem +0 -0
- data/docs/core/1_overview.md +77 -0
- data/docs/core/2_architecture.md +92 -0
- data/docs/core/3_service_objects.md +121 -0
- data/docs/features/1_schema_validation.md +119 -0
- data/docs/features/2_error_handling.md +121 -0
- data/docs/features/3_async_execution.md +81 -0
- data/docs/features/4_logging.md +64 -0
- data/docs/guides/1_common_patterns.md +90 -0
- data/docs/guides/2_migration_guide.md +175 -0
- data/docs/integration/1_configuration.md +51 -0
- data/docs/integration/2_testing.md +164 -0
- data/docs/integration/3_rails_integration.md +99 -0
- data/docs/yard/Servus/Base.html +1645 -0
- data/docs/yard/Servus/Config.html +582 -0
- data/docs/yard/Servus/Extensions/Async/Call.html +400 -0
- data/docs/yard/Servus/Extensions/Async/Errors/AsyncError.html +140 -0
- data/docs/yard/Servus/Extensions/Async/Errors/JobEnqueueError.html +154 -0
- data/docs/yard/Servus/Extensions/Async/Errors/ServiceNotFoundError.html +154 -0
- data/docs/yard/Servus/Extensions/Async/Errors.html +128 -0
- data/docs/yard/Servus/Extensions/Async/Ext.html +119 -0
- data/docs/yard/Servus/Extensions/Async/Job.html +310 -0
- data/docs/yard/Servus/Extensions/Async.html +141 -0
- data/docs/yard/Servus/Extensions.html +117 -0
- data/docs/yard/Servus/Generators/ServiceGenerator.html +261 -0
- data/docs/yard/Servus/Generators.html +115 -0
- data/docs/yard/Servus/Helpers/ControllerHelpers.html +457 -0
- data/docs/yard/Servus/Helpers.html +115 -0
- data/docs/yard/Servus/Railtie.html +134 -0
- data/docs/yard/Servus/Support/Errors/AuthenticationError.html +287 -0
- data/docs/yard/Servus/Support/Errors/BadRequestError.html +283 -0
- data/docs/yard/Servus/Support/Errors/ForbiddenError.html +284 -0
- data/docs/yard/Servus/Support/Errors/InternalServerError.html +283 -0
- data/docs/yard/Servus/Support/Errors/NotFoundError.html +284 -0
- data/docs/yard/Servus/Support/Errors/ServiceError.html +489 -0
- data/docs/yard/Servus/Support/Errors/ServiceUnavailableError.html +290 -0
- data/docs/yard/Servus/Support/Errors/UnauthorizedError.html +200 -0
- data/docs/yard/Servus/Support/Errors/UnprocessableEntityError.html +288 -0
- data/docs/yard/Servus/Support/Errors/ValidationError.html +200 -0
- data/docs/yard/Servus/Support/Errors.html +140 -0
- data/docs/yard/Servus/Support/Logger.html +856 -0
- data/docs/yard/Servus/Support/Rescuer/BlockContext.html +585 -0
- data/docs/yard/Servus/Support/Rescuer/CallOverride.html +257 -0
- data/docs/yard/Servus/Support/Rescuer/ClassMethods.html +343 -0
- data/docs/yard/Servus/Support/Rescuer.html +267 -0
- data/docs/yard/Servus/Support/Response.html +574 -0
- data/docs/yard/Servus/Support/Validator.html +1150 -0
- data/docs/yard/Servus/Support.html +119 -0
- data/docs/yard/Servus/Testing/ExampleBuilders.html +523 -0
- data/docs/yard/Servus/Testing/ExampleExtractor.html +578 -0
- data/docs/yard/Servus/Testing.html +142 -0
- data/docs/yard/Servus.html +343 -0
- data/docs/yard/_index.html +535 -0
- data/docs/yard/class_list.html +54 -0
- data/docs/yard/css/common.css +1 -0
- data/docs/yard/css/full_list.css +58 -0
- data/docs/yard/css/style.css +503 -0
- data/docs/yard/file.1_common_patterns.html +154 -0
- data/docs/yard/file.1_configuration.html +115 -0
- data/docs/yard/file.1_overview.html +142 -0
- data/docs/yard/file.1_schema_validation.html +188 -0
- data/docs/yard/file.2_architecture.html +157 -0
- data/docs/yard/file.2_error_handling.html +190 -0
- data/docs/yard/file.2_migration_guide.html +242 -0
- data/docs/yard/file.2_testing.html +227 -0
- data/docs/yard/file.3_async_execution.html +145 -0
- data/docs/yard/file.3_rails_integration.html +160 -0
- data/docs/yard/file.3_service_objects.html +191 -0
- data/docs/yard/file.4_logging.html +135 -0
- data/docs/yard/file.ErrorHandling.html +190 -0
- data/docs/yard/file.READme.html +674 -0
- data/docs/yard/file.architecture.html +157 -0
- data/docs/yard/file.async_execution.html +145 -0
- data/docs/yard/file.common_patterns.html +154 -0
- data/docs/yard/file.configuration.html +115 -0
- data/docs/yard/file.error_handling.html +190 -0
- data/docs/yard/file.logging.html +135 -0
- data/docs/yard/file.migration_guide.html +242 -0
- data/docs/yard/file.overview.html +142 -0
- data/docs/yard/file.rails_integration.html +160 -0
- data/docs/yard/file.schema_validation.html +188 -0
- data/docs/yard/file.service_objects.html +191 -0
- data/docs/yard/file.testing.html +227 -0
- data/docs/yard/file_list.html +119 -0
- data/docs/yard/frames.html +22 -0
- data/docs/yard/index.html +674 -0
- data/docs/yard/js/app.js +344 -0
- data/docs/yard/js/full_list.js +242 -0
- data/docs/yard/js/jquery.js +4 -0
- data/docs/yard/method_list.html +542 -0
- data/docs/yard/top-level-namespace.html +110 -0
- data/lib/generators/servus/service/service_generator.rb +64 -1
- data/lib/generators/servus/service/templates/service.rb.erb +1 -1
- data/lib/servus/base.rb +258 -57
- data/lib/servus/config.rb +58 -12
- data/lib/servus/extensions/async/call.rb +50 -18
- data/lib/servus/extensions/async/errors.rb +23 -3
- data/lib/servus/extensions/async/ext.rb +10 -2
- data/lib/servus/extensions/async/job.rb +32 -11
- data/lib/servus/helpers/controller_helpers.rb +73 -37
- data/lib/servus/support/errors.rb +135 -45
- data/lib/servus/support/rescuer.rb +189 -36
- data/lib/servus/support/response.rb +49 -7
- data/lib/servus/support/validator.rb +120 -19
- data/lib/servus/testing/example_builders.rb +133 -0
- data/lib/servus/testing/example_extractor.rb +309 -0
- data/lib/servus/testing.rb +17 -0
- data/lib/servus/version.rb +1 -1
- metadata +118 -19
|
@@ -0,0 +1,135 @@
|
|
|
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 / 4. Logging
|
|
8
|
+
|
|
9
|
+
— 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 = "4_logging";
|
|
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> »
|
|
40
|
+
<span class="title">File: Features / 4. Logging</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="logging">Logging</h1>
|
|
61
|
+
|
|
62
|
+
<p>Servus automatically logs all service executions with timing information. No instrumentation code needed in services.</p>
|
|
63
|
+
|
|
64
|
+
<h2 id="what-gets-logged">What Gets Logged</h2>
|
|
65
|
+
|
|
66
|
+
<p><strong>Service calls</strong> (DEBUG): Service class name and arguments</p>
|
|
67
|
+
|
|
68
|
+
<pre class="code ruby"><code class="ruby">[Servus] Users::Create::Service called with {:email=>"user@example.com", :name=>"John"}
|
|
69
|
+
</code></pre>
|
|
70
|
+
|
|
71
|
+
<p><strong>Successful completions</strong> (INFO): Service class name and duration</p>
|
|
72
|
+
|
|
73
|
+
<pre class="code ruby"><code class="ruby">[Servus] Users::Create::Service completed successfully in 0.0243s
|
|
74
|
+
</code></pre>
|
|
75
|
+
|
|
76
|
+
<p><strong>Failures</strong> (WARN): Service class name, error type, message, and duration</p>
|
|
77
|
+
|
|
78
|
+
<pre class="code ruby"><code class="ruby">[Servus] Users::Create::Service failed with NotFoundError: User not found (0.0125s)
|
|
79
|
+
</code></pre>
|
|
80
|
+
|
|
81
|
+
<p><strong>Exceptions</strong> (ERROR): Service class name, exception type, message, and duration</p>
|
|
82
|
+
|
|
83
|
+
<pre class="code ruby"><code class="ruby">[Servus] Users::Create::Service raised ArgumentError: Missing required field (0.0089s)
|
|
84
|
+
</code></pre>
|
|
85
|
+
|
|
86
|
+
<h2 id="log-levels">Log Levels</h2>
|
|
87
|
+
|
|
88
|
+
<p>Servus uses Rails.logger and respects application log level configuration:</p>
|
|
89
|
+
|
|
90
|
+
<ul>
|
|
91
|
+
<li><strong>DEBUG</strong>: Shows arguments (use in development, hide in production to avoid logging sensitive data)</li>
|
|
92
|
+
<li><strong>INFO</strong>: Shows completions (normal operations)</li>
|
|
93
|
+
<li><strong>WARN</strong>: Shows business failures</li>
|
|
94
|
+
<li><strong>ERROR</strong>: Shows system exceptions</li>
|
|
95
|
+
</ul>
|
|
96
|
+
|
|
97
|
+
<p>Set production log level to INFO to hide argument logging:</p>
|
|
98
|
+
|
|
99
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'># config/environments/production.rb
|
|
100
|
+
</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>
|
|
101
|
+
</code></pre>
|
|
102
|
+
|
|
103
|
+
<h2 id="sensitive-data">Sensitive Data</h2>
|
|
104
|
+
|
|
105
|
+
<p>Arguments are logged at DEBUG level. In production, either:</p>
|
|
106
|
+
|
|
107
|
+
<ol>
|
|
108
|
+
<li>Set log level to INFO (recommended)</li>
|
|
109
|
+
<li>Use Rails parameter filtering: <code>config.filter_parameters += [:password, :ssn, :credit_card]</code></li>
|
|
110
|
+
<li>Pass IDs instead of full objects: <code>Service.call(user_id: 1)</code> not <code>Service.call(user: user_object)</code></li>
|
|
111
|
+
</ol>
|
|
112
|
+
|
|
113
|
+
<h2 id="integration-with-logging-tools">Integration with Logging Tools</h2>
|
|
114
|
+
|
|
115
|
+
<p>The <code>[Servus]</code> prefix makes service logs easy to grep and filter:</p>
|
|
116
|
+
|
|
117
|
+
<pre class="code bash"><code class="bash"># Find all service calls
|
|
118
|
+
grep "\[Servus\]" production.log
|
|
119
|
+
|
|
120
|
+
# Find slow services
|
|
121
|
+
grep "completed" production.log | grep "Servus" | awk '{print $NF}' | sort -n
|
|
122
|
+
</code></pre>
|
|
123
|
+
|
|
124
|
+
<p>Servus logs work with structured logging tools (Lograge, Datadog, Splunk) without modification.</p>
|
|
125
|
+
</div></div>
|
|
126
|
+
|
|
127
|
+
<div id="footer">
|
|
128
|
+
Generated on Fri Nov 21 00:33:23 2025 by
|
|
129
|
+
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
|
130
|
+
0.9.37 (ruby-3.4.4).
|
|
131
|
+
</div>
|
|
132
|
+
|
|
133
|
+
</div>
|
|
134
|
+
</body>
|
|
135
|
+
</html>
|
|
@@ -0,0 +1,190 @@
|
|
|
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: ErrorHandling
|
|
8
|
+
|
|
9
|
+
— 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 = "ErrorHandling";
|
|
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> »
|
|
40
|
+
<span class="title">File: ErrorHandling</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="error-handling">Error Handling</h1>
|
|
61
|
+
|
|
62
|
+
<p>Servus distinguishes between expected business failures (return failure) and unexpected system errors (raise exceptions). This separation makes error handling predictable and explicit.</p>
|
|
63
|
+
|
|
64
|
+
<h2 id="failures-vs-exceptions">Failures vs Exceptions</h2>
|
|
65
|
+
|
|
66
|
+
<p><strong>Use <code>failure()</code></strong> for expected business conditions:</p>
|
|
67
|
+
|
|
68
|
+
<ul>
|
|
69
|
+
<li>User not found</li>
|
|
70
|
+
<li>Insufficient balance</li>
|
|
71
|
+
<li>Invalid state transition</li>
|
|
72
|
+
</ul>
|
|
73
|
+
|
|
74
|
+
<p><strong>Use <code>error!()</code> or raise</strong> for unexpected system errors:</p>
|
|
75
|
+
|
|
76
|
+
<ul>
|
|
77
|
+
<li>Database connection failure</li>
|
|
78
|
+
<li>Nil reference error</li>
|
|
79
|
+
<li>External API timeout</li>
|
|
80
|
+
</ul>
|
|
81
|
+
|
|
82
|
+
<p>Failures return a Response object so callers can handle them. Exceptions halt execution and bubble up.</p>
|
|
83
|
+
|
|
84
|
+
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
|
|
85
|
+
<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'>id:</span> <span class='id identifier rubyid_user_id'>user_id</span><span class='rparen'>)</span>
|
|
86
|
+
<span class='kw'>return</span> <span class='id identifier rubyid_failure'>failure</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>User not found</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='label'>type:</span> <span class='const'>NotFoundError</span><span class='rparen'>)</span> <span class='kw'>unless</span> <span class='id identifier rubyid_user'>user</span>
|
|
87
|
+
<span class='kw'>return</span> <span class='id identifier rubyid_failure'>failure</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Insufficient funds</span><span class='tstring_end'>"</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'>>=</span> <span class='id identifier rubyid_amount'>amount</span>
|
|
88
|
+
|
|
89
|
+
<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='id identifier rubyid_amount'>amount</span><span class='rparen'>)</span> <span class='comment'># Raises on system error
|
|
90
|
+
</span> <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>
|
|
91
|
+
<span class='kw'>end</span>
|
|
92
|
+
</code></pre>
|
|
93
|
+
|
|
94
|
+
<h2 id="error-classes">Error Classes</h2>
|
|
95
|
+
|
|
96
|
+
<p>All error classes inherit from <code>ServiceError</code> and map to HTTP status codes. Use them for API-friendly errors.</p>
|
|
97
|
+
|
|
98
|
+
<pre class="code ruby"><code class="ruby"><span class='comment'># Built-in errors
|
|
99
|
+
</span><span class='const'>NotFoundError</span> <span class='comment'># 404
|
|
100
|
+
</span><span class='const'>BadRequestError</span> <span class='comment'># 400
|
|
101
|
+
</span><span class='const'>UnauthorizedError</span> <span class='comment'># 401
|
|
102
|
+
</span><span class='const'>ForbiddenError</span> <span class='comment'># 403
|
|
103
|
+
</span><span class='const'>ValidationError</span> <span class='comment'># 422
|
|
104
|
+
</span><span class='const'>InternalServerError</span> <span class='comment'># 500
|
|
105
|
+
</span><span class='const'>ServiceUnavailableError</span> <span class='comment'># 503
|
|
106
|
+
</span>
|
|
107
|
+
<span class='comment'># Usage
|
|
108
|
+
</span><span class='id identifier rubyid_failure'>failure</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Resource not found</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='label'>type:</span> <span class='const'>NotFoundError</span><span class='rparen'>)</span>
|
|
109
|
+
<span class='id identifier rubyid_error!'>error!</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Database corrupted</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='label'>type:</span> <span class='const'>InternalServerError</span><span class='rparen'>)</span> <span class='comment'># Raises exception
|
|
110
|
+
</span></code></pre>
|
|
111
|
+
|
|
112
|
+
<p>Each error has an <code>api_error</code> method returning <code>{ code: :symbol, message: "string" }</code> for JSON APIs.</p>
|
|
113
|
+
|
|
114
|
+
<h2 id="declarative-exception-handling">Declarative Exception Handling</h2>
|
|
115
|
+
|
|
116
|
+
<p>Use <code>rescue_from</code> to convert specific exceptions into failures. Original exception details are preserved in error messages.</p>
|
|
117
|
+
|
|
118
|
+
<pre class="code ruby"><code class="ruby">class CallExternalApi::Service < Servus::Base
|
|
119
|
+
rescue_from Net::HTTPError, Timeout::Error use: ServiceUnavailableError
|
|
120
|
+
rescue_from JSON::ParserError, use: BadRequestError
|
|
121
|
+
|
|
122
|
+
def call
|
|
123
|
+
response = http_client.get(url) # May raise
|
|
124
|
+
data = JSON.parse(response.body) # May raise
|
|
125
|
+
success(data: data)
|
|
126
|
+
end
|
|
127
|
+
end
|
|
128
|
+
|
|
129
|
+
# If Net::HTTPError is raised, service returns:
|
|
130
|
+
# Response(success: false, error: ServiceUnavailableError("[Net::HTTPError]: original message"))
|
|
131
|
+
</code></pre>
|
|
132
|
+
|
|
133
|
+
<p>The <code>rescue_from</code> pattern keeps business logic clean while ensuring consistent error handling across services.</p>
|
|
134
|
+
|
|
135
|
+
<h3 id="custom-error-handling-with-blocks">Custom Error Handling with Blocks</h3>
|
|
136
|
+
|
|
137
|
+
<p>For more control over error handling, provide a block to <code>rescue_from</code>. The block receives the exception and can return either success or failure:</p>
|
|
138
|
+
|
|
139
|
+
<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'><</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>
|
|
140
|
+
<span class='comment'># Custom failure with error details
|
|
141
|
+
</span> <span class='id identifier rubyid_rescue_from'>rescue_from</span> <span class='const'>ActiveRecord</span><span class='op'>::</span><span class='const'>RecordInvalid</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_exception'>exception</span><span class='op'>|</span>
|
|
142
|
+
<span class='id identifier rubyid_failure'>failure</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Payment failed: </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_exception'>exception</span><span class='period'>.</span><span class='id identifier rubyid_record'>record</span><span class='period'>.</span><span class='id identifier rubyid_errors'>errors</span><span class='period'>.</span><span class='id identifier rubyid_full_messages'>full_messages</span><span class='period'>.</span><span class='id identifier rubyid_join'>join</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>, </span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='embexpr_end'>}</span><span class='tstring_end'>"</span></span><span class='comma'>,</span>
|
|
143
|
+
<span class='label'>type:</span> <span class='const'>ValidationError</span><span class='rparen'>)</span>
|
|
144
|
+
<span class='kw'>end</span>
|
|
145
|
+
|
|
146
|
+
<span class='comment'># Recover from certain errors with success
|
|
147
|
+
</span> <span class='id identifier rubyid_rescue_from'>rescue_from</span> <span class='const'>Stripe</span><span class='op'>::</span><span class='const'>CardError</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_exception'>exception</span><span class='op'>|</span>
|
|
148
|
+
<span class='kw'>if</span> <span class='id identifier rubyid_exception'>exception</span><span class='period'>.</span><span class='id identifier rubyid_code'>code</span> <span class='op'>==</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>card_declined</span><span class='tstring_end'>'</span></span>
|
|
149
|
+
<span class='id identifier rubyid_failure'>failure</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Card was declined</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='label'>type:</span> <span class='const'>BadRequestError</span><span class='rparen'>)</span>
|
|
150
|
+
<span class='kw'>else</span>
|
|
151
|
+
<span class='comment'># Log and continue for other card errors
|
|
152
|
+
</span> <span class='const'>Rails</span><span class='period'>.</span><span class='id identifier rubyid_logger'>logger</span><span class='period'>.</span><span class='id identifier rubyid_warn'>warn</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Stripe error: </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_exception'>exception</span><span class='period'>.</span><span class='id identifier rubyid_message'>message</span><span class='embexpr_end'>}</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span>
|
|
153
|
+
<span class='id identifier rubyid_success'>success</span><span class='lparen'>(</span><span class='label'>recovered:</span> <span class='kw'>true</span><span class='comma'>,</span> <span class='label'>fallback_used:</span> <span class='kw'>true</span><span class='rparen'>)</span>
|
|
154
|
+
<span class='kw'>end</span>
|
|
155
|
+
<span class='kw'>end</span>
|
|
156
|
+
|
|
157
|
+
<span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
|
|
158
|
+
<span class='comment'># Service logic that may raise exceptions
|
|
159
|
+
</span> <span class='kw'>end</span>
|
|
160
|
+
<span class='kw'>end</span>
|
|
161
|
+
</code></pre>
|
|
162
|
+
|
|
163
|
+
<p>The block has access to <code>success(data)</code> and <code>failure(message, type:)</code> methods. This allows conditional error handling and even recovering from exceptions.</p>
|
|
164
|
+
|
|
165
|
+
<h2 id="custom-errors">Custom Errors</h2>
|
|
166
|
+
|
|
167
|
+
<p>Create domain-specific errors by inheriting from <code>ServiceError</code>:</p>
|
|
168
|
+
|
|
169
|
+
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>InsufficientFundsError</span> <span class='op'><</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/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/Errors.html" title="Servus::Support::Errors (module)">Errors</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Support/Errors/ServiceError.html" title="Servus::Support::Errors::ServiceError (class)">ServiceError</a></span></span>
|
|
170
|
+
<span class='const'>DEFAULT_MESSAGE</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Insufficient funds</span><span class='tstring_end'>"</span></span>
|
|
171
|
+
|
|
172
|
+
<span class='kw'>def</span> <span class='id identifier rubyid_api_error'>api_error</span>
|
|
173
|
+
<span class='lbrace'>{</span> <span class='label'>code:</span> <span class='symbol'>:insufficient_funds</span><span class='comma'>,</span> <span class='label'>message:</span> <span class='id identifier rubyid_message'>message</span> <span class='rbrace'>}</span>
|
|
174
|
+
<span class='kw'>end</span>
|
|
175
|
+
<span class='kw'>end</span>
|
|
176
|
+
|
|
177
|
+
<span class='comment'># Usage
|
|
178
|
+
</span><span class='id identifier rubyid_failure'>failure</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Account balance too low</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='label'>type:</span> <span class='const'>InsufficientFundsError</span><span class='rparen'>)</span>
|
|
179
|
+
</code></pre>
|
|
180
|
+
</div></div>
|
|
181
|
+
|
|
182
|
+
<div id="footer">
|
|
183
|
+
Generated on Fri Nov 21 00:23:02 2025 by
|
|
184
|
+
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
|
185
|
+
0.9.37 (ruby-3.4.4).
|
|
186
|
+
</div>
|
|
187
|
+
|
|
188
|
+
</div>
|
|
189
|
+
</body>
|
|
190
|
+
</html>
|