servus 1.2.0 → 1.3.1

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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 10e4e061222d303e5d694d816afd1d0557eb6c4e7804dd5b454e48cddcdf0797
4
- data.tar.gz: b6cdb1fcabe827988e6e8daf44d20d2da2649cf4b252d36ac68dd1f8f14db584
3
+ metadata.gz: 1ed0c555ab8879d5f5e32ecfed8109214468bbd3f9a397a4d6b1a79df51cc2e8
4
+ data.tar.gz: e518983727d4fad53fe08ef7863692cfa06c002b2a4a9248b38b8a25c3f2371d
5
5
  SHA512:
6
- metadata.gz: 61ab96b3ed1da09eb768ced10cbacc5cb6f4e8a8f4aead7ed57aa6f49dbdd016513dee1f1f2402a7a21504913b9ae5c0ef23298301fc398c3dcb6f224d2dcedc
7
- data.tar.gz: 011eaaabc88c46604d60c9f82727e43f6152521a7f1cb64b483a1b912eb0a047eaf8607eab31b51f31a92df90333c4130af845f10a8d7263aa3bcfd3fda85f60
6
+ metadata.gz: ddece449340240ced0d0df59d9c1eb9ed79e5e03ffd8ffd6cb5a402dd8d206d13489ef9da9d7e7b49dc98d2b2abff5cb78f235ccfdda6d085abfa96f36b4fb14
7
+ data.tar.gz: ffc7bd55d38b027005eb89187b4987776e546a9bb85d33c2566848704d1f787fb2e985700b921a57add2356ce67e9f877985fdae7d86fc52767055c2ecdb05b9
data/lib/servus/config.rb CHANGED
@@ -90,6 +90,36 @@ module Servus
90
90
  # end
91
91
  attr_accessor :logger
92
92
 
93
+ # What to add to every event payload, beside what each event is about.
94
+ #
95
+ # A callable given the payload as built, the event's name and the service
96
+ # emitting it (+nil+ for {Servus::Event.emit}), returning the payload to
97
+ # validate and dispatch. Applied on both emission paths, before the payload
98
+ # is validated, so an Event's schema can require what it adds. Use it for
99
+ # what every event should say the same way, such as who caused it, rather
100
+ # than having each service build it into its own payloads.
101
+ #
102
+ # @return [#call, nil] the enricher, or nil to emit payloads as built
103
+ #
104
+ # @example Say who caused every event
105
+ # config.event_payload_enricher = lambda do |payload, event_name:, service:|
106
+ # payload.merge(meta: { actor: Current.user&.id })
107
+ # end
108
+ attr_accessor :event_payload_enricher
109
+
110
+ # The payload an event is emitted with: as built, or as the configured
111
+ # {#event_payload_enricher} returns it.
112
+ #
113
+ # @param payload [Hash] the payload as built
114
+ # @param event_name [Symbol] the event being emitted
115
+ # @param service [Servus::Base, nil] the service emitting it, if one is
116
+ # @return [Hash] the payload to validate and dispatch
117
+ def enrich_event_payload(payload, event_name:, service: nil)
118
+ return payload unless event_payload_enricher
119
+
120
+ event_payload_enricher.call(payload, event_name:, service:)
121
+ end
122
+
93
123
  # The ordered list of routers that resolve invocations for events.
94
124
  #
95
125
  # The Bus iterates routers in order, collects invocations, deduplicates
data/lib/servus/event.rb CHANGED
@@ -202,6 +202,9 @@ module Servus
202
202
  #
203
203
  # Provides a type-safe, discoverable way to emit events from anywhere in
204
204
  # the application (controllers, jobs, rake tasks) without creating a service.
205
+ # The payload is given to the configured
206
+ # {Servus::Config#event_payload_enricher}, with no service, before it is
207
+ # validated.
205
208
  #
206
209
  # @param payload [Hash] the event payload
207
210
  # @return [void]
@@ -226,6 +229,7 @@ module Servus
226
229
  def emit(payload)
227
230
  raise 'No event configured. Call event_name :name first.' unless @event_name
228
231
 
232
+ payload = Servus.config.enrich_event_payload(payload, event_name: @event_name)
229
233
  Servus::Support::Validator.validate_event_payload!(self, payload)
230
234
 
231
235
  Servus::Events::Bus.emit(@event_name, payload)
@@ -146,7 +146,9 @@ module Servus
146
146
  end
147
147
  end
148
148
 
149
- # Emits events for a specific trigger with the given result.
149
+ # Emits events for a specific trigger with the given result. Each payload
150
+ # is built, then given to the configured
151
+ # {Servus::Config#event_payload_enricher}, then validated and dispatched.
150
152
  #
151
153
  # @param trigger [Symbol] the trigger type (:success, :failure, :error!)
152
154
  # @param result [Servus::Support::Response] the service result
@@ -156,7 +158,9 @@ module Servus
156
158
  self.class.emissions_for(trigger).each do |emission|
157
159
  next unless emission_condition_met?(emission, result)
158
160
 
159
- payload = build_event_payload(emission, result)
161
+ payload = Servus.config.enrich_event_payload(build_event_payload(emission, result),
162
+ event_name: emission[:event_name],
163
+ service: self)
160
164
  validate_event_payload!(emission[:event_name], payload)
161
165
  Servus::Events::Bus.emit(emission[:event_name], payload)
162
166
  end
@@ -175,6 +175,11 @@ module Servus
175
175
  # Generates a named job subclass for this service and installs it as a sibling
176
176
  # constant in the service's parent namespace.
177
177
  #
178
+ # The job subclasses its parent service's job (see {#parent_servus_job_class}),
179
+ # so whatever a base service configures with {#async} — queue, priority,
180
+ # +retry_on+, callbacks — every service beneath it inherits, and a service's
181
+ # own {#async} overrides it as an ActiveJob subclass overrides its parent.
182
+ #
178
183
  # The constant is +"#{ServiceConst}Job"+, so +Treasury::TransferGold::Service+
179
184
  # yields +Treasury::TransferGold::ServiceJob+. Defining it eagerly (see
180
185
  # {#inherited}) means Rails' production eager-load defines every service's job
@@ -191,7 +196,7 @@ module Servus
191
196
  def build_servus_job_class
192
197
  raise Servus::Events::Errors::AnonymousServiceError.for(self) if name.nil?
193
198
 
194
- klass = Class.new(Servus::Extensions::Async::Job)
199
+ klass = Class.new(parent_servus_job_class)
195
200
  klass.servus_service = self
196
201
 
197
202
  publish_job_const(servus_job_const_name, klass)
@@ -199,6 +204,20 @@ module Servus
199
204
  klass
200
205
  end
201
206
 
207
+ # The job class this service's job subclasses: its parent service's, so job
208
+ # configuration follows the service hierarchy. A service directly beneath
209
+ # {Servus::Base}, or beneath an anonymous service with no job of its own,
210
+ # starts from {Servus::Extensions::Async::Job}.
211
+ #
212
+ # @return [Class<Servus::Extensions::Async::Job>] the job class to subclass
213
+ # @api private
214
+ def parent_servus_job_class
215
+ parent = superclass
216
+ return Servus::Extensions::Async::Job unless parent < Servus::Base && parent.name
217
+
218
+ parent.servus_job_class
219
+ end
220
+
202
221
  # @return [String] the sibling constant the service's job is published under
203
222
  # @api private
204
223
  def servus_job_const_name
@@ -30,8 +30,6 @@ module Servus
30
30
  # @return [Class<Servus::Base>, nil] the owning service class
31
31
  class_attribute :servus_service
32
32
 
33
- queue_as :default
34
-
35
33
  # Executes the job's service with the provided arguments.
36
34
  #
37
35
  # The service is identified by {servus_service} rather than a serialized
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Servus
4
- VERSION = '1.2.0'
4
+ VERSION = '1.3.1'
5
5
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: servus
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.2.0
4
+ version: 1.3.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Sebastian Scholl
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-10-22 00:00:00.000000000 Z
11
+ date: 2026-11-04 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: activesupport