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.1_schema_validation.html ADDED
@@ -0,0 +1,188 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>
7
+ File: Features / 1. Schema Validation
8
+
9
+ &mdash; Servus | Service Object Framework
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" />
16
+
17
+ <script type="text/javascript">
18
+ pathId = "1_schema_validation";
19
+ relpath = '';
20
+ </script>
21
+
22
+
23
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
24
+
25
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
26
+
27
+
28
+ </head>
29
+ <body>
30
+ <div class="nav_wrap">
31
+ <iframe id="nav" src="file_list.html?1"></iframe>
32
+ <div id="resizer"></div>
33
+ </div>
34
+
35
+ <div id="main" tabindex="-1">
36
+ <div id="header">
37
+ <div id="menu">
38
+
39
+ <a href="_index.html">Index</a> &raquo;
40
+ <span class="title">File: Features / 1. Schema Validation</span>
41
+
42
+ </div>
43
+
44
+ <div id="search">
45
+
46
+ <a class="full_list_link" id="class_list_link"
47
+ href="class_list.html">
48
+
49
+ <svg width="24" height="24">
50
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
51
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
52
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
53
+ </svg>
54
+ </a>
55
+
56
+ </div>
57
+ <div class="clear"></div>
58
+ </div>
59
+
60
+ <div id="content"><div id='filecontents'><h1 id="schema-validation">Schema Validation</h1>
61
+
62
+ <p>Servus provides optional JSON Schema validation for service arguments and results. Validation is opt-in - services work fine without schemas.</p>
63
+
64
+ <h2 id="how-it-works">How It Works</h2>
65
+
66
+ <p>Define schemas using the <code>schema</code> DSL method (recommended) or as constants. The framework validates arguments before execution and results after execution. Invalid data raises <code>ValidationError</code>.</p>
67
+
68
+ <h3 id="preferred-schema-dsl-method">Preferred: Schema DSL Method</h3>
69
+
70
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>ProcessPayment</span><span class='op'>::</span><span class='const'>Service</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Base.html" title="Servus::Base (class)">Base</a></span></span>
71
+ <span class='id identifier rubyid_schema'>schema</span><span class='lparen'>(</span>
72
+ <span class='label'>arguments:</span> <span class='lbrace'>{</span>
73
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>object</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
74
+ <span class='label'>required:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>user_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>amount</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
75
+ <span class='label'>properties:</span> <span class='lbrace'>{</span>
76
+ <span class='label'>user_id:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>integer</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>example:</span> <span class='int'>123</span> <span class='rbrace'>}</span><span class='comma'>,</span>
77
+ <span class='label'>amount:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>number</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>minimum:</span> <span class='float'>0.01</span><span class='comma'>,</span> <span class='label'>example:</span> <span class='float'>100.0</span> <span class='rbrace'>}</span>
78
+ <span class='rbrace'>}</span>
79
+ <span class='rbrace'>}</span><span class='comma'>,</span>
80
+ <span class='label'>result:</span> <span class='lbrace'>{</span>
81
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>object</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
82
+ <span class='label'>required:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>transaction_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>new_balance</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
83
+ <span class='label'>properties:</span> <span class='lbrace'>{</span>
84
+ <span class='label'>transaction_id:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>string</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>example:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>txn_abc123</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
85
+ <span class='label'>new_balance:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>number</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>example:</span> <span class='float'>950.0</span> <span class='rbrace'>}</span>
86
+ <span class='rbrace'>}</span>
87
+ <span class='rbrace'>}</span>
88
+ <span class='rparen'>)</span>
89
+ <span class='kw'>end</span>
90
+ </code></pre>
91
+
92
+ <p><strong>Pro tip:</strong> Add <code>example</code> or <code>examples</code> keywords to your schemas. These values can be automatically extracted in tests using <code>servus_arguments_example()</code> and <code>servus_result_example()</code> helpers. See the <a href="../integration/testing.md#schema-example-helpers">Testing documentation</a> for details.</p>
93
+
94
+ <p>You can define just one schema if needed:</p>
95
+
96
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>SendEmail</span><span class='op'>::</span><span class='const'>Service</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Base.html" title="Servus::Base (class)">Base</a></span></span>
97
+ <span class='id identifier rubyid_schema'>schema</span> <span class='label'>arguments:</span> <span class='lbrace'>{</span>
98
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>object</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
99
+ <span class='label'>required:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>email</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>subject</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
100
+ <span class='label'>properties:</span> <span class='lbrace'>{</span>
101
+ <span class='label'>email:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>string</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>email</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
102
+ <span class='label'>subject:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>string</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span>
103
+ <span class='rbrace'>}</span>
104
+ <span class='rbrace'>}</span>
105
+ <span class='kw'>end</span>
106
+ </code></pre>
107
+
108
+ <h3 id="alternative-inline-constants">Alternative: Inline Constants</h3>
109
+
110
+ <p>Constants are still supported for backwards compatibility:</p>
111
+
112
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>ProcessPayment</span><span class='op'>::</span><span class='const'>Service</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Base.html" title="Servus::Base (class)">Base</a></span></span>
113
+ <span class='const'>ARGUMENTS_SCHEMA</span> <span class='op'>=</span> <span class='lbrace'>{</span>
114
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>object</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
115
+ <span class='label'>required:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>user_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>amount</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
116
+ <span class='label'>properties:</span> <span class='lbrace'>{</span>
117
+ <span class='label'>user_id:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>integer</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
118
+ <span class='label'>amount:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>number</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>minimum:</span> <span class='float'>0.01</span> <span class='rbrace'>}</span>
119
+ <span class='rbrace'>}</span>
120
+ <span class='rbrace'>}</span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span>
121
+
122
+ <span class='const'>RESULT_SCHEMA</span> <span class='op'>=</span> <span class='lbrace'>{</span>
123
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>object</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
124
+ <span class='label'>required:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>transaction_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>new_balance</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span><span class='comma'>,</span>
125
+ <span class='label'>properties:</span> <span class='lbrace'>{</span>
126
+ <span class='label'>transaction_id:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>string</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
127
+ <span class='label'>new_balance:</span> <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>number</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span>
128
+ <span class='rbrace'>}</span>
129
+ <span class='rbrace'>}</span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span>
130
+ <span class='kw'>end</span>
131
+ </code></pre>
132
+
133
+ <h2 id="file-based-schemas">File-Based Schemas</h2>
134
+
135
+ <p>For complex schemas, use JSON files instead of inline definitions. Create files at:</p>
136
+
137
+ <ul>
138
+ <li><code>app/schemas/services/service_name/arguments.json</code></li>
139
+ <li><code>app/schemas/services/service_name/result.json</code></li>
140
+ </ul>
141
+
142
+ <h3 id="schema-lookup-precedence">Schema Lookup Precedence</h3>
143
+
144
+ <p>Servus checks for schemas in this order:</p>
145
+
146
+ <ol>
147
+ <li><strong>schema DSL method</strong> (if defined)</li>
148
+ <li><strong>Inline constants</strong> (ARGUMENTS_SCHEMA, RESULT_SCHEMA)</li>
149
+ <li><strong>JSON files</strong> (in schema_root directory)</li>
150
+ </ol>
151
+
152
+ <p>Schemas are cached after first load for performance.</p>
153
+
154
+ <h2 id="three-layers-of-validation">Three Layers of Validation</h2>
155
+
156
+ <p><strong>Schema Validation</strong> (Servus): Type safety and structure at service boundaries</p>
157
+
158
+ <p><strong>Business Rules</strong> (Service Logic): Domain-specific constraints during execution</p>
159
+
160
+ <p><strong>Model Validation</strong> (ActiveRecord): Database constraints before persistence</p>
161
+
162
+ <p>Each layer has a different purpose - don&#39;t duplicate validation across layers.</p>
163
+
164
+ <h2 id="configuration">Configuration</h2>
165
+
166
+ <p>Change the schema file location if needed:</p>
167
+
168
+ <pre class="code ruby"><code class="ruby"><span class='comment'># config/initializers/servus.rb
169
+ </span><span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Servus.html#configure-class_method" title="Servus.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
170
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_schema_root'>schema_root</span> <span class='op'>=</span> <span class='const'>Rails</span><span class='period'>.</span><span class='id identifier rubyid_root'>root</span><span class='period'>.</span><span class='id identifier rubyid_join'>join</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>config/schemas</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
171
+ <span class='kw'>end</span>
172
+ </code></pre>
173
+
174
+ <p>Clear the schema cache during development when schemas change:</p>
175
+
176
+ <pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="Servus.html" title="Servus (module)">Servus</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Support.html" title="Servus::Support (module)">Support</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Servus/Support/Validator.html" title="Servus::Support::Validator (class)">Validator</a></span></span><span class='period'>.</span><span class='id identifier rubyid_clear_cache!'><span class='object_link'><a href="Servus/Support/Validator.html#clear_cache!-class_method" title="Servus::Support::Validator.clear_cache! (method)">clear_cache!</a></span></span>
177
+ </code></pre>
178
+ </div></div>
179
+
180
+ <div id="footer">
181
+ Generated on Fri Nov 21 00:33:23 2025 by
182
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
183
+ 0.9.37 (ruby-3.4.4).
184
+ </div>
185
+
186
+ </div>
187
+ </body>
188
+ </html>
data/docs/yard/file.2_architecture.html ADDED
@@ -0,0 +1,157 @@
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 / 2. Architecture
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 = "2_architecture";
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 / 2. Architecture</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="architecture">Architecture</h1>
61
+
62
+ <p>Servus wraps service execution with automatic validation, logging, and error handling. When you call <code>Service.call(**args)</code>, the framework orchestrates these concerns transparently.</p>
63
+
64
+ <h2 id="execution-flow">Execution Flow</h2>
65
+
66
+ <pre class="code ruby"><code class="ruby"><span class='const'>Arguments</span> <span class='id identifier rubyid_→'>→</span> <span class='const'>Validation</span> <span class='id identifier rubyid_→'>→</span> <span class='const'>Service</span><span class='comment'>#call → Result Validation → Logging → Response
67
+ </span> <span class='id identifier rubyid_↓'>↓</span> <span class='id identifier rubyid_↓'>↓</span> <span class='id identifier rubyid_↓'>↓</span>
68
+ <span class='const'>ValidationError</span> <span class='const'>ValidationError</span> <span class='const'>Benchmark</span>
69
+ </code></pre>
70
+
71
+ <p>The framework intercepts the <code>.call</code> class method to inject cross-cutting concerns before and after your business logic runs. Your <code>call</code> instance method contains only business logic - validation, logging, and timing happen automatically.</p>
72
+
73
+ <h2 id="core-components">Core Components</h2>
74
+
75
+ <p><strong>Servus::Base</strong> (<code>lib/servus/base.rb</code>): Foundation class providing <code>.call()</code> orchestration and response helpers (<code>success</code>, <code>failure</code>, <code>error!</code>)</p>
76
+
77
+ <p><strong>Support::Response</strong> (<code>lib/servus/support/response.rb</code>): Immutable result object with <code>success?</code>, <code>data</code>, and <code>error</code> attributes</p>
78
+
79
+ <p><strong>Support::Validator</strong> (<code>lib/servus/support/validator.rb</code>): JSON Schema validation for arguments (before execution) and results (after execution). Schemas are cached after first load.</p>
80
+
81
+ <p><strong>Support::Logger</strong> (<code>lib/servus/support/logger.rb</code>): Automatic logging at DEBUG (calls with args), INFO (success), WARN (failures), ERROR (exceptions)</p>
82
+
83
+ <p><strong>Support::Rescuer</strong> (<code>lib/servus/support/rescuer.rb</code>): Declarative exception handling via <code>rescue_from</code> class method</p>
84
+
85
+ <p><strong>Support::Errors</strong> (<code>lib/servus/support/errors.rb</code>): HTTP-aligned error hierarchy (ServiceError, NotFoundError, ValidationError, etc.)</p>
86
+
87
+ <h2 id="extension-points">Extension Points</h2>
88
+
89
+ <h3 id="schema-validation">Schema Validation</h3>
90
+
91
+ <p>Use the <code>schema</code> DSL method to define JSON Schema validation for arguments and results:</p>
92
+
93
+ <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>
94
+ <span class='id identifier rubyid_schema'>schema</span><span class='lparen'>(</span>
95
+ <span class='label'>arguments:</span> <span class='lbrace'>{</span> <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> <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='rbracket'>]</span> <span class='rbrace'>}</span><span class='comma'>,</span>
96
+ <span class='label'>result:</span> <span class='lbrace'>{</span> <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> <span class='label'>required:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>user</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span> <span class='rbrace'>}</span>
97
+ <span class='rparen'>)</span>
98
+ <span class='kw'>end</span>
99
+ </code></pre>
100
+
101
+ <h3 id="declarative-error-handling">Declarative Error Handling</h3>
102
+
103
+ <p>Use <code>rescue_from</code> to convert exceptions into failures. Provide a custom error type or use a block for custom handling.</p>
104
+
105
+ <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>
106
+ <span class='comment'># Default error type
107
+ </span> <span class='id identifier rubyid_rescue_from'>rescue_from</span> <span class='const'>Net</span><span class='op'>::</span><span class='const'>HTTPError</span><span class='comma'>,</span> <span class='const'>Timeout</span><span class='op'>::</span><span class='const'>Error</span><span class='comma'>,</span> <span class='label'>use:</span> <span class='const'>ServiceUnavailableError</span>
108
+
109
+ <span class='comment'># Custom handling with block
110
+ </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>
111
+ <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'>Validation failed: </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'>&quot;</span></span><span class='comma'>,</span> <span class='label'>type:</span> <span class='const'>ValidationError</span><span class='rparen'>)</span>
112
+ <span class='kw'>end</span>
113
+ <span class='kw'>end</span>
114
+ </code></pre>
115
+
116
+ <h3 id="support-classes">Support Classes</h3>
117
+
118
+ <p>Create helper classes in <code>app/services/service_name/support/*.rb</code>. These are namespaced to your service.</p>
119
+
120
+ <pre class="code ruby"><code class="ruby">app/services/process_payment/
121
+ ├── service.rb
122
+ └── support/
123
+ ├── payment_gateway.rb
124
+ └── receipt_formatter.rb
125
+ </code></pre>
126
+
127
+ <h2 id="async-execution">Async Execution</h2>
128
+
129
+ <p><code>Service.call_async(**args)</code> enqueues execution via ActiveJob. The service runs identically whether called sync or async.</p>
130
+
131
+ <pre class="code ruby"><code class="ruby"><span class='const'>ProcessPayment</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>
132
+ <span class='label'>user_id:</span> <span class='int'>1</span><span class='comma'>,</span>
133
+ <span class='label'>amount:</span> <span class='int'>50</span><span class='comma'>,</span>
134
+ <span class='label'>queue:</span> <span class='symbol'>:critical</span><span class='comma'>,</span>
135
+ <span class='label'>wait:</span> <span class='int'>5</span><span class='period'>.</span><span class='id identifier rubyid_minutes'>minutes</span>
136
+ <span class='rparen'>)</span>
137
+ </code></pre>
138
+
139
+ <h2 id="performance">Performance</h2>
140
+
141
+ <ul>
142
+ <li>Schema loading: Cached per class after first use</li>
143
+ <li>Validation overhead: ~1-5ms when schemas defined</li>
144
+ <li>Logging overhead: ~0.1ms per call</li>
145
+ <li>Total framework overhead: &lt; 10ms per service call</li>
146
+ </ul>
147
+ </div></div>
148
+
149
+ <div id="footer">
150
+ Generated on Fri Nov 21 00:33:23 2025 by
151
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
152
+ 0.9.37 (ruby-3.4.4).
153
+ </div>
154
+
155
+ </div>
156
+ </body>
157
+ </html>
data/docs/yard/file.2_error_handling.html ADDED
@@ -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: Features / 2. Error Handling
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 = "2_error_handling";
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 / 2. Error Handling</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'>&quot;</span><span class='tstring_content'>User not found</span><span class='tstring_end'>&quot;</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'>&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='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'>&quot;</span><span class='tstring_content'>Resource not found</span><span class='tstring_end'>&quot;</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'>&quot;</span><span class='tstring_content'>Database corrupted</span><span class='tstring_end'>&quot;</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: &quot;string&quot; }</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 &lt; 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(&quot;[Net::HTTPError]: original message&quot;))
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'>&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>
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'>&quot;</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'>&#39;</span><span class='tstring_content'>, </span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</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'>&#39;</span><span class='tstring_content'>card_declined</span><span class='tstring_end'>&#39;</span></span>
149
+ <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'>Card was declined</span><span class='tstring_end'>&quot;</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'>&quot;</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'>&quot;</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'>&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/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'>&quot;</span><span class='tstring_content'>Insufficient funds</span><span class='tstring_end'>&quot;</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'>&quot;</span><span class='tstring_content'>Account balance too low</span><span class='tstring_end'>&quot;</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:33:23 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>