event_rail 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3367f3d4d8f5eb0841f1cca4021af4faa7a3fac3bf1a94edb328f5206eccd516
-  data.tar.gz: 795013406723b9b46fc5e5ca4532a0a2b5f35c0ab9ca3a49240bb63c09b13ead
+  metadata.gz: 1306e3a4d6e6b69ce720544a4368fa1f7201e29c55651ec6a2e5d8a4d35efcd2
+  data.tar.gz: 58597eac171bf85d946e4b063edafe88b71869c0daba79061384ea649d1a27e1
 SHA512:
-  metadata.gz: 3df1e24c288ab7f89544af2286456e5e2a9f64ed7155a83479794fda04728c86b71cbf9f8486d9dc09873a9a35920efe316acf25211be3eeb6111e3be326ee96
-  data.tar.gz: cd069c5dcd53f4195e5171db86cbe75cfece2dfbbf1218c36710cf2fc54e9b5a932a48eaa685d9b5abc8eb6b75ad6cef24fc00bb40bd070032ce5397b1c6a3ed
+  metadata.gz: fd0e456db39d2fce3e1c14fd5e302b011e5b67f4c9d04ecbed62ff19e545c0ab7f2964bce49945bed15f578a82d03b51b6cf307b30cbe50226c74e6b3424c391
+  data.tar.gz: 8f460442f9509d71b6132236252399a109456e22e0d72cda816ce618948215bc5a90de844067b31cb0cb7efbaf512fb75aae9acae1172ab4a3860668b6c2ef03

data/CHANGELOG.md

@@ -13,6 +13,36 @@ here unless a release changes how they behave.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-29
+
+### Added
+
+- **`EventRail.stage(event, identity:, source:)` records an event with the transaction that
+  changes the state it reports.** It stamps the event exactly as `publish` does, builds one
+  job per subscriber, and hands them all to your stager in one call instead of enqueuing
+  them. The stager persists them with the caller's transaction, all or nothing, and hands
+  them to the queue after the commit, so the intent to deliver commits or rolls back with the
+  data. This closes the gap at a boundary, such as a controller action, that has no job retry
+  to republish after a crash. EventRail ships no table or relay; the README gives two recipes,
+  an outbox table and a queue that shares the application's database.
+- **`config.event_rail.stager`**: the name of a constant that responds to `stage(jobs)`,
+  resolved on every staging so a reloaded class is always the current one, or an object used
+  as given. Preparation fails for a name that resolves to nothing or a stager without `stage`.
+  An application that never stages configures nothing.
+- **`EventRail::StagedPublication`**, what `stage` returns: the stamped event, the staged
+  jobs, and their subscriber classes. It has no accepted or skipped outcomes, because a
+  subscriber's enqueue callbacks run when its job is enqueued, not when it is staged.
+- **`stage.event_rail`**, a fifth notification, carrying `subscriber_count` beside the usual
+  keys.
+
+### Changed
+
+- `EventRail::TransactionalPublicationError` now names staging through a configured stager
+  as the alternative to publishing after the commit. `publish` inside a transaction still
+  raises.
+- Staging shares publication's duplicate check within one job attempt: staging or publishing
+  the same fact twice raises `EventRail::DuplicatePublicationError`.
+
 ## [0.4.0] - 2026-09-26
 
 ### Changed
@@ -158,7 +188,8 @@ here unless a release changes how they behave.
 - A typed error hierarchy rooted at `EventRail::Error`, distinguishing declaration,
   casting, context, serialization, and publication failures.
 
-[Unreleased]: https://github.com/alexdmtv/event-rail/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/alexdmtv/event-rail/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/alexdmtv/event-rail/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/alexdmtv/event-rail/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/alexdmtv/event-rail/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/alexdmtv/event-rail/compare/v0.1.0...v0.2.0

data/README.md

@@ -37,7 +37,7 @@ EventRail is narrow on purpose: durable fanout across a boundary inside one appl
 ### What it does not do
 
 - **No event log and no synchronous handlers.** No history, replay, read-model rebuild, or browser UI, and every subscriber crosses the queue. A subscriber can append every event to a store of your own, keyed on `(source, id)`, but that store is a downstream log, not event sourcing: publication follows the commit, with no ordering or expected-version guarantees, so the store is a copy of what happened rather than its source of truth.
-- **No outbox, and so a dual-write gap.** Publication is refused inside a transaction, so a publisher commits and then publishes, and a process that dies between the two loses the event. Publishing from a job makes that recoverable, because the retry republishes under the same identity (see [Replay-safe publishers](#replay-safe-publishers)); a controller action has no retry to repeat the publication, though an event with declared identity keeps its ID when anything does. An application that wants recovery beyond that records the intent to publish in the same transaction as its data, and a sweeper or a relay job publishes it; an event with [declared identity](#identity-occurrence-time-and-source) derives the same ID however many times it is republished, so consumers see a repetition rather than a new fact.
+- **No outbox of its own.** Publication is refused inside a transaction, so a publisher that publishes commits first, and a process that dies between the two loses the event. Publishing from a job makes that recoverable, because the retry republishes under the same identity (see [Replay-safe publishers](#replay-safe-publishers)). A controller action has no such retry, so at a boundary [stage the event](#staging-inside-a-database-transaction) instead: its subscriber jobs are recorded in the same transaction as the data, through a stager your application supplies, and handed to the queue after the commit. EventRail ships no table and no relay for it; the README gives two recipes.
 - **Discovery is enforced, not advisory.** A subscriber outside a [discovery root](#where-discovery-looks) fails the boot rather than being quietly ignored: a silent delivery bug traded for a loud startup error, at the price of a layout rule.
 
 ## Requirements
@@ -240,10 +240,167 @@ Retries, backoff, discarding, and dead-letter handling stay where they already a
 
 ### Publishing inside a database transaction
 
-Don't. Publication raises `EventRail::TransactionalPublicationError` when a transaction is open, in every environment, and the fix is to publish after the transaction commits.
+Don't. Publication raises `EventRail::TransactionalPublicationError` when a transaction is open, in every environment. The fix is to publish after the transaction commits, or to [stage the event](#staging-inside-a-database-transaction) within it.
 
 Both queue deferral settings are wrong inside a transaction, in opposite directions. With `enqueue_after_transaction_commit` on, the enqueue is deferred past the point where its failure can be reported, so a publication that silently enqueued nothing looks successful. With it off, the enqueue announces a fact that a rollback then contradicts. The check is on the open transaction itself, so it does not depend on the setting, or on Active Record being present at all.
 
+### Staging inside a database transaction
+
+`EventRail.stage` records an event with the transaction that changes the state it reports. It stamps the event exactly as `publish` does, builds one job per subscriber, and hands them all to your **stager** in one call instead of enqueuing them:
+
+```ruby
+staged = EventRail.stage(
+  Docs::OrderPlaced.new(order_id: "A-1003", total: "10.00", placed_at: Time.now.utc.iso8601)
+)
+
+staged                     # an EventRail::StagedPublication
+staged.event               # the stamped, immutable fact, as publish would stamp it
+staged.staged_jobs         # one unenqueued job per subscriber, as the stager received them
+staged.staged_subscribers  # their classes
+```
+
+The stager persists the jobs with the caller's transaction and hands them to the queue once it commits, so the intent to deliver commits or rolls back with the state change. Configure it once, by name:
+
+```ruby
+# doc:illustrative
+# config/application.rb
+config.event_rail.stager = "StagedJob"   # resolved on every staging, so a reload is followed
+
+# app/models/order.rb
+def ship!
+  transaction do
+    update!(state: "shipped")
+    EventRail.stage(Orders::OrderShipped.new(order_id: id))
+  end
+end
+```
+
+`config.event_rail.stager` takes the name of a constant, as a String or a Symbol, resolved each time an event is staged, or an object used as given. Use the name for anything in your application's reloadable code: a class held by reference fails at boot or goes stale after a reload. An object suits a stager in a gem or under `autoload_once_paths`; `lib/` is reloadable once `config.autoload_lib` covers it. Preparation checks that the name resolves and that the stager responds to `stage`, so a typo fails the boot. `EventRail.stage` with no stager configured raises `EventRail::ConfigurationError`; an application that never stages configures nothing.
+
+Staging shares publication's duplicate check. Staging or publishing the same fact twice in one job attempt raises `EventRail::DuplicatePublicationError`, and a stager that raises leaves the fact free to be staged again in that attempt, under the same ID. One consequence: a job that stages, has its transaction roll back, and stages again in the same attempt fails as a duplicate, and only its own `retry_on` runs it again. Outside a job there is no duplicate check, and an event without declared identity gets a new ID each time, so **an event staged at a boundary, where a request may be repeated, should declare its identity** or be staged with `identity:`.
+
+#### The stager contract
+
+A stager is any object with one method, `stage(jobs)`, which receives an array of unenqueued Active Job instances, possibly empty, and its own to change. EventRail calls it even for an event with no subscribers, so the stager's own checks hold either way. Everything else is the stager's:
+
+- **All or nothing.** It persists the whole list with the caller's open transaction, or raises. A failure part-way through must not leave earlier jobs behind, even if the caller rescues the error and commits. Atomicity with the business state comes from letting the error propagate: rescuing a staging error and committing drops the event, as rescuing any failed write drops that write.
+- **The transaction check.** Only the stager knows which database it writes to, so it decides whether a suitable transaction is open, and it should raise when none is. Staging outside one reopens the gap staging exists to close: an `update!` that autocommits, then a staged row written separately.
+- **Persistence, not delivery.** What commits with the transaction is the intent to deliver. Delivery then depends on the hand-over, the relay, the queue, and each subscriber's own enqueue callbacks, which run when a job is enqueued rather than when it is staged. A callback that declines the job is the subscriber's decision; the stager decides what it means.
+- **Deferral.** A stager that deletes a staged job must do so only after the queue has actually accepted it. Active Job reports a deferred enqueue as successful before it happens, so hand over only once every open transaction has committed (`ActiveRecord.after_all_transactions_commit`), when an enqueue is immediate whatever the setting. Rails 7.2 applications on `load_defaults "7.2"` defer by default. Whether deferral is in effect differs by version, and Active Job reads the setting when a job is enqueued: on 7.2, `:never` is off, `:always` is on, and any other value, `false` included, asks the queue adapter; on 8.0, `:never` and `:default` are off and `:always` is on, with a deprecation warning, and otherwise a truthy value is on; from 8.1 any truthy value is on, the old symbols included.
+- **Hand-over errors.** A hand-over runs after the caller's transaction has committed, so an error there has nobody to go to: rescue it and leave the job for the relay.
+- **Duplicates.** A job handed over twice is delivered twice under the same event ID. A retried staging builds new jobs, with new job IDs, under the same event ID. Subscribers are idempotent on `(source, id)` either way.
+- **What a staged job carries.** It is built at staging, with the staging context's origin time already in place. Its queue and priority are resolved when the stager serializes or enqueues it; options passed through `set`, and anything a custom `perform_later` does, are not applied. It names its job class and holds EventRail's serialized event, so a renamed subscriber or a changed format follows the same rules as a job already in the queue.
+- **Limits.** Staging the same fact again from inside `stage` is not supported. EventRail provides no storage, relay, ordering or retention for staged jobs.
+
+For a database per module, one stager can route: stage into whichever store has an open application transaction, and raise when none or several do. A transaction should never span modules, so several open is a bug, and call sites stay `EventRail.stage(event)` when a module moves to its own database.
+
+#### Recipe: an outbox table
+
+A table in the application's database, written in the caller's transaction and drained after the commit, with a relay for anything the immediate hand-over missed:
+
+```ruby
+# doc:illustrative
+# create_table :staged_jobs do |t|
+#   t.string :job_id, null: false, index: { unique: true }
+#   t.json :payload, null: false
+#   t.datetime :created_at, null: false
+# end
+class StagedJob < ApplicationRecord
+  # One insert_all! statement writes every row or none. Not insert_all, which skips a
+  # conflicting row without saying so.
+  def self.stage(jobs)
+    raise ArgumentError, "#{name}.stage needs an open transaction to commit with" unless current_transaction.open?
+    return if jobs.empty?
+
+    now = Time.current
+    insert_all!(jobs.map { |job| { job_id: job.job_id, payload: job.serialize, created_at: now } })
+
+    # After every open transaction commits, so the enqueue is immediate whatever the
+    # deferral setting, and a row is never deleted for an enqueue that was only deferred.
+    ActiveRecord.after_all_transactions_commit { jobs.each { |job| hand_over(job) } }
+  end
+
+  # Deletes the row once the queue took the job, or once a subscriber's own enqueue callback
+  # declined it; anything else leaves it for the relay.
+  def self.hand_over(job)
+    job.enqueue
+    if job.enqueue_error
+      Rails.logger.warn("Staged job #{job.job_id} left for the relay: #{job.enqueue_error.message}")
+    else
+      Rails.logger.warn("Staged job #{job.job_id} declined by its enqueue callback") unless job.successfully_enqueued?
+      where(job_id: job.job_id).delete_all
+    end
+  rescue => error
+    Rails.logger.warn("Staged job #{job.job_id} left for the relay: #{error.class}: #{error.message}")
+  end
+
+  # Run on a schedule, every second or so. A row that cannot even be loaded -- its job class
+  # renamed while it waited -- is left and logged, and the rows after it are still handed over.
+  def self.relay(older_than: 5.seconds)
+    where(created_at: ...older_than.ago).find_each do |row|
+      hand_over(ActiveJob::Base.deserialize(row.payload))
+    rescue => error
+      Rails.logger.warn("Staged job #{row.job_id} left for the relay: #{error.class}: #{error.message}")
+    end
+  end
+end
+```
+
+#### Recipe: a queue in your database
+
+A queue whose tables share the application's database and connection, such as GoodJob or Solid Queue configured without a separate database, needs no outbox: enqueuing in the transaction is itself the staging. Two conditions EventRail cannot check for you: the queue must use the same connection as the transaction, and deferral must actually be off for every staged job, or the enqueue becomes an after-commit hook that is not durable. Subscribers' enqueue callbacks run inside the transaction here.
+
+```ruby
+# doc:illustrative
+module QueueStager
+  module_function
+
+  def stage(jobs)
+    raise ArgumentError, "QueueStager.stage needs an open transaction" unless ApplicationRecord.current_transaction.open?
+
+    deferred = jobs.map(&:class).uniq.select { |job_class| deferred?(job_class) }
+    raise ArgumentError, "#{deferred.map(&:name).join(", ")} defer enqueuing until after commit" if deferred.any?
+
+    # A savepoint, so a later job's failure takes the earlier ones with it even if the
+    # caller rescues the error and commits.
+    ApplicationRecord.transaction(requires_new: true) do
+      jobs.each do |job|
+        job.enqueue
+        raise job.enqueue_error if job.enqueue_error
+      end
+    end
+  end
+
+  # Whether Active Job would defer this class's enqueue to after the commit. The setting's
+  # meaning moved between versions, and it is interpreted when a job is enqueued, not when it
+  # is set.
+  def deferred?(job_class)
+    setting = job_class.enqueue_after_transaction_commit
+
+    if ActiveJob.version < Gem::Version.new("8.0")
+      # 7.2: the adapter decides unless the class said :never or :always.
+      case setting
+      when :never then false
+      when :always then true
+      else job_class.queue_adapter.enqueue_after_transaction_commit?
+      end
+    elsif ActiveJob.version < Gem::Version.new("8.1")
+      # 8.0: the old symbols still mean what they meant, with a deprecation warning.
+      case setting
+      when :never, :default then false
+      when :always then true
+      else setting ? true : false
+      end
+    else
+      # 8.1 on: any truthy value defers, the old symbols included.
+      setting ? true : false
+    end
+  end
+end
+```
+
+Both recipes are exercised against real transactions in EventRail's own test suite, adapted to its test tables, including a check of the deferral rule against what each supported Rails version actually does.
+
 ### Replay-safe publishers
 
 A publisher that applies a state transition and then publishes should make the transition idempotent and attempt publication unconditionally:
@@ -462,7 +619,7 @@ assert_enqueued_with(job: Docs::Billing::ChargeCardJob, args: [ publication.even
 perform_enqueued_jobs
 ```
 
-`assert_enqueued_with(args:)` works because events are value objects. For observability assertions, subscribe to the notifications below. EventRail ships no assertion library, observer, or contract-test helper; Active Job's helpers are the whole assertion surface.
+`assert_enqueued_with(args:)` works because events are value objects. A staged event reaches the same assertions once its transaction commits and your stager hands its jobs over, so configure your real stager in the test environment: Rails' transactional tests hide their own transaction, so a transaction your code opens runs its commit callbacks, and the hand-over, when its block completes. For observability assertions, subscribe to the notifications below. EventRail ships no assertion library, observer, or contract-test helper; Active Job's helpers are the whole assertion surface.
 
 ### Tests that need their own fixtures
 
@@ -522,11 +679,12 @@ Activation replaces a process-wide registry, so it is not safe under `paralleliz
 
 ## Notifications
 
-Four `ActiveSupport::Notifications` events, all in block form so Rails' own exception keys report failures:
+Five `ActiveSupport::Notifications` events, all in block form so Rails' own exception keys report failures:
 
 | Name | Additional payload |
 | --- | --- |
 | `publish.event_rail` | `subscriber_count`, `accepted`, `skipped` |
+| `stage.event_rail` | `subscriber_count` |
 | `enqueue_subscriber.event_rail` | `job_class`, `outcome` (`accepted`, `skipped`, `failed`) |
 | `deserialize.event_rail` | `format_version` |
 | `perform_subscriber.event_rail` | `job_class` |

data/lib/event_rail/errors.rb

@@ -14,8 +14,10 @@ module EventRail
   end
 
   # An application's own configuration is wrong: a discovery root that is not an autoload
-  # root of the application or any engine. Distinct from a declaration fault, which is about
-  # a class body, and raised at preparation so it fails the boot that introduced it.
+  # root of the application or any engine, or a stager that cannot be resolved or cannot
+  # stage. Distinct from a declaration fault, which is about a class body. Raised at
+  # preparation where it can be, so it fails the boot that introduced it, and by
+  # `EventRail.stage` when no stager is configured at all.
   class ConfigurationError < Error
   end
 
@@ -171,12 +173,13 @@ module EventRail
   # Publication happened inside an open application database transaction. Both queue
   # deferral settings are wrong there, in opposite directions: a deferred enqueue
   # cannot report its own failure, and an immediate one announces a fact a rollback
-  # then contradicts.
+  # then contradicts. Staging is the way to record an event with the transaction.
   class TransactionalPublicationError < PublicationError
     def initialize(message = nil)
       super(
         message ||
-          "cannot publish inside an open database transaction; publish after the transaction commits"
+          "cannot publish inside an open database transaction; publish after the transaction commits, " \
+          "or stage the event within it through a configured stager (EventRail.stage)"
       )
     end
   end

data/lib/event_rail/internal/execution.rb

@@ -73,6 +73,15 @@ module EventRail
         @publications[key] = Record.new(event: event, succeeded: succeeded)
       end
 
+      # Puts back what `record` returned earlier: nil forgets the key entirely.
+      def restore!(key, record)
+        if record.nil?
+          @publications.delete(key)
+        else
+          @publications[key] = record
+        end
+      end
+
       # What one logical publication looked like the last time this attempt tried it.
       # Retaining the failed case is what lets the same attempt retry complete fanout
       # under the identity it already stamped, instead of manufacturing a second one.

data/lib/event_rail/internal/notifications.rb

@@ -2,7 +2,7 @@ require "active_support/notifications"
 
 module EventRail
   module Internal
-    # Payloads for the four public notifications.
+    # Payloads for the five public notifications.
     #
     # Contract, identity, and lineage only. Domain data and extensions are excluded by
     # construction rather than by filtering, because a notification payload reaches logs

data/lib/event_rail/internal/registry.rb

@@ -140,6 +140,7 @@ module EventRail
             @building = true
             begin
               eager_load_conventional_roots
+              Stager.validate!
               prune_stale_declarations
               @snapshot = build_snapshot
             ensure

data/lib/event_rail/internal/stager.rb

@@ -0,0 +1,99 @@
+module EventRail
+  module Internal
+    # Finds the application's stager: what `EventRail.stage` hands an event's subscriber
+    # jobs to, in place of enqueuing them.
+    #
+    # Configured by name as a rule. A stager is usually an application model, which cannot be
+    # loaded while `config/application.rb` or an initializer runs and is replaced on every
+    # reload in development, so a class held by reference would either fail the boot or go
+    # stale. The name is resolved again on every staging, the way `belongs_to` resolves
+    # `class_name:`. An object is used as given, for a stager that is never reloaded.
+    module Stager
+      SETTING = "config.event_rail.stager".freeze
+      # Ruby's own rule for a constant name, Unicode included: an uppercase letter, then word
+      # characters.
+      CONSTANT_PATH = /\A(?:::)?[[:upper:]][[:word:]]*(?:::[[:upper:]][[:word:]]*)*\z/
+
+      module_function
+
+      # The configured value, or a configuration error when there is no Rails application
+      # to read it from: staging has nowhere else to find a stager.
+      def configured
+        unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+          raise ConfigurationError,
+            "EventRail.stage reads #{SETTING} from the Rails application, and there is none"
+        end
+
+        ::Rails.application.config.event_rail&.stager
+      end
+
+      def resolve(configured)
+        if configured.nil?
+          raise ConfigurationError,
+            "EventRail.stage needs a stager; set #{SETTING} to the name of a class that responds to stage(jobs)"
+        end
+
+        stager = configured.is_a?(String) || configured.is_a?(Symbol) ? constantize(configured.to_s) : configured
+        return stager if stager.respond_to?(:stage)
+
+        raise ConfigurationError, "#{SETTING} is #{configured.inspect}, which does not respond to stage(jobs)"
+      end
+
+      # Called from preparation, which runs after the autoloaders are set up and again on
+      # every reload, so a misspelled name or a missing method fails the boot that
+      # introduced it rather than the first staging. Nothing to check without a Rails
+      # application, or with no stager configured: an application that never stages needs
+      # none.
+      def validate!
+        return unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+        value = configured
+        resolve(value) unless value.nil?
+      end
+
+      # Only a constant the name itself denotes being missing is a configuration error: the
+      # name, or one of the namespaces it passes through. That is decided by where the lookup
+      # failed -- which constant was missing, and in which namespace -- rather than by comparing
+      # strings, so a name that passes through an alias of a namespace is judged by the
+      # namespace it reaches. Anything else raised while loading the stager is a bug in its
+      # file, left alone so its backtrace points there: a NameError naming no constant, one
+      # missing from some other namespace, or Zeitwerk's, which means the file exists and
+      # defines the wrong thing.
+      def constantize(name)
+        unless name.match?(CONSTANT_PATH)
+          raise ConfigurationError, "#{SETTING} is #{name.inspect}, which is not a constant name"
+        end
+
+        ActiveSupport::Inflector.constantize(name)
+      rescue NameError => error
+        raise if defined?(::Zeitwerk::NameError) && error.is_a?(::Zeitwerk::NameError)
+        raise unless missing_from(name, error)
+
+        raise ConfigurationError, "#{SETTING} names #{name.inspect}, which is not a constant"
+      end
+
+      def missing_from(name, error)
+        return false if error.name.nil?
+
+        receiver = begin
+          error.receiver
+        rescue ArgumentError
+          return false # raised by hand, with no namespace it was looked up in
+        end
+
+        segments = name.delete_prefix("::").split("::")
+        segments.each_index.any? do |index|
+          segments[index] == error.name.to_s && namespace(segments.first(index)).equal?(receiver)
+        end
+      end
+
+      def namespace(segments)
+        return Object if segments.empty?
+
+        ActiveSupport::Inflector.constantize(segments.join("::"))
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

data/lib/event_rail/internal/stamping.rb

@@ -8,7 +8,9 @@ module EventRail
     module Stamping
       module_function
 
-      Prepared = Struct.new(:event, :execution, :logical_key, :relayed, keyword_init: true) do
+      # `previous` is the record this publication found for its fact, nil for a first attempt, so
+      # a caller that fails before delivering anything can put it back (`abandon!`).
+      Prepared = Struct.new(:event, :execution, :logical_key, :relayed, :previous, keyword_init: true) do
         def relayed?
           relayed
         end
@@ -55,7 +57,7 @@ module EventRail
 
         execution.record!(logical_key, event: stamped, succeeded: false) if execution&.derives_identity?
 
-        Prepared.new(event: stamped, execution: execution, logical_key: logical_key, relayed: false)
+        Prepared.new(event: stamped, execution: execution, logical_key: logical_key, relayed: false, previous: recorded)
       end
 
       def succeeded!(prepared)
@@ -65,6 +67,17 @@ module EventRail
         execution.record!(prepared.logical_key, event: prepared.event, succeeded: true)
       end
 
+      # Undoes `prepare` for a publication that failed before handing anything over, restoring
+      # what the execution recorded before it: nothing for a first attempt, the earlier failed
+      # attempt otherwise. Without this a failure that delivered nothing would still turn the
+      # next publication of the fact into a retry, bound to a payload nobody received.
+      def abandon!(prepared)
+        execution = prepared.execution
+        return unless execution&.derives_identity?
+
+        execution.restore!(prepared.logical_key, prepared.previous)
+      end
+
       # A relayed fact belongs to its origin. Its ID, source, occurrence time, lineage
       # -- an absent causation included -- and extensions are preserved, and the relaying
       # application's own context is deliberately not merged in: local baggage is not
@@ -85,6 +98,7 @@ module EventRail
 
         execution = Execution.current
         logical_key = record_key(event.source, event, event.id)
+        recorded = nil
 
         if execution&.derives_identity?
           recorded = execution.record(logical_key)
@@ -97,7 +111,7 @@ module EventRail
           execution.record!(logical_key, event: event, succeeded: false)
         end
 
-        Prepared.new(event: event, execution: execution, logical_key: logical_key, relayed: true)
+        Prepared.new(event: event, execution: execution, logical_key: logical_key, relayed: true, previous: recorded)
       end
       private_class_method :relay
 

data/lib/event_rail/publish.rb

@@ -19,12 +19,7 @@ module EventRail
     # subscriber's enqueue fails, and the retry repeats complete fanout under the same
     # event ID, so a subscriber may see the same event more than once.
     def publish(event, identity: nil, source: nil, **unknown)
-      if unknown.key?(:key)
-        raise ArgumentError,
-          "publish's key: is now identity:, and it names a fact across every job rather than within one; " \
-          "check the value names one occurrence per source and event type before renaming it"
-      end
-      raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.keys.map(&:inspect).join(", ")}" if unknown.any?
+      reject_unknown_keywords!(:publish, unknown)
 
       Internal::Transaction.check!
 
@@ -55,6 +50,15 @@ module EventRail
     end
 
     private
+      def reject_unknown_keywords!(verb, unknown)
+        if unknown.key?(:key)
+          raise ArgumentError,
+            "#{verb}'s key: is now identity:, and it names a fact across every job rather than within one; " \
+            "check the value names one occurrence per source and event type before renaming it"
+        end
+        raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.keys.map(&:inspect).join(", ")}" if unknown.any?
+      end
+
       # Three outcomes, not two. Active Job returns false both when an adapter reports
       # failure and when an enqueue callback aborts, so the return value alone cannot
       # tell a fault from a decision. The job instance can, through `enqueue_error`, and

data/lib/event_rail/railtie.rb

@@ -12,6 +12,12 @@ module EventRail
     config.event_rail = ActiveSupport::OrderedOptions.new
     config.event_rail.roots = Internal::Registry::DEFAULT_ROOTS.dup
 
+    # What `EventRail.stage` hands an event's subscriber jobs to: the name of a constant,
+    # resolved on every staging so a reloaded class is always the current one, or an object
+    # for a stager that is never reloaded. Either responds to `stage(jobs)`. Assigned
+    # explicitly, so the option exists before an application sets it.
+    config.event_rail.stager = nil
+
     config.to_prepare do
       # Unqualified, so lexical lookup reaches the private Internal namespace that a
       # qualified EventRail::Internal reference would be refused.

data/lib/event_rail/stage.rb

@@ -0,0 +1,79 @@
+require "active_support/notifications"
+
+module EventRail
+  class << self
+    # Stages an event: stamps it exactly as `publish` does, builds one job per declared
+    # subscriber without enqueuing any, and hands them all to the application's stager in one
+    # call, inside the caller's database transaction.
+    #
+    #   Order.transaction do
+    #     order.update!(state: "shipped")
+    #     EventRail.stage(Orders::OrderShipped.new(order_id: order.id))
+    #   end
+    #
+    # The stager (`config.event_rail.stager`) persists the jobs with that transaction, all or
+    # nothing, or raises, and hands them to the queue once it commits. So the intent to
+    # deliver commits or rolls back with the state change it reports. Delivery itself is the
+    # stager's: its hand-over, its relay, the queue, and each subscriber's own enqueue
+    # callbacks, which run when a job is enqueued rather than here.
+    #
+    # Unlike `publish`, staging inside an open transaction is the point, so there is no
+    # transaction check. Whether the right transaction is open is the stager's to judge: only
+    # it knows which database it writes to.
+    def stage(event, identity: nil, source: nil, **unknown)
+      reject_unknown_keywords!(:stage, unknown)
+
+      # Every check that can fail on configuration or readiness runs before stamping, which
+      # records the fact in the current execution: a failure here must not leave a record that
+      # makes the next staging in the same attempt look like a retry. Readiness before the
+      # stager, so staging from an initializer says "not ready" rather than failing to find a
+      # class the autoloader cannot load yet.
+      configured = Internal::Stager.configured
+      snapshot = Internal::Registry.snapshot
+      stager = Internal::Stager.resolve(configured)
+
+      prepared = Internal::Stamping.prepare(event, identity: identity, source: source)
+      stamped = prepared.event
+      handed_over = false
+
+      begin
+        jobs = snapshot.subscribers_for(stamped.class).map { |job_class| staged_job(job_class, stamped) }.freeze
+
+        ActiveSupport::Notifications.instrument("stage.event_rail", Internal::Notifications.payload_for(stamped)) do |payload|
+          payload[:subscriber_count] = jobs.length
+          handed_over = true
+
+          # Called even with no jobs, so the stager's own transaction check applies whether or
+          # not the event has subscribers yet: otherwise adding the first one would make a
+          # previously silent call site start raising. A copy, so the stager may sort or trim
+          # its argument without touching what the result reports.
+          stager.stage(jobs.dup)
+        end
+      ensure
+        # A failure before the stager was called -- a subscriber that cannot be built, a
+        # notification handler failing as the block starts -- handed nothing over, so it must
+        # not leave the fact recorded: the next staging in this attempt is a first staging, not
+        # a retry bound to a payload no stager saw. From the stager on, a failure leaves the
+        # fact unfinished, and staging it again is a retry.
+        Internal::Stamping.abandon!(prepared) unless handed_over
+      end
+
+      # After the notification block, as for `publish`.
+      Internal::Stamping.succeeded!(prepared)
+
+      StagedPublication.new(event: stamped, staged_jobs: jobs)
+    end
+
+    private
+      # The job `perform_later` would have built, without the enqueue. Its context entry is
+      # built now, while the staging context is current, so the stager may serialize the job
+      # whenever and wherever it likes and still write what enqueuing it here would have
+      # written. Through the entry alone, not `serialize`: serializing would resolve and
+      # memoize the job's queue and priority blocks inside the caller's context and run its
+      # argument serializers for nothing. Every subscriber includes JobContext; preparation
+      # refuses one that does not.
+      def staged_job(job_class, event)
+        job_class.new(event).tap { |job| job.send(:__event_rail_entry__) }
+      end
+  end
+end

data/lib/event_rail/staged_publication.rb

@@ -0,0 +1,34 @@
+module EventRail
+  # What `EventRail.stage` returns: the stamped fact, and the subscriber jobs handed to the
+  # stager in place of being enqueued.
+  #
+  # Not a `Publication`. Accepted and skipped are outcomes of an enqueue, and staging performs
+  # none: whether each job reaches the queue, and whether a subscriber's own enqueue callback
+  # declines it, is decided later, when the stager hands it over. The jobs are here so a
+  # caller can match their IDs with what its stager wrote.
+  class StagedPublication
+    attr_reader :event, :staged_jobs
+
+    def initialize(event:, staged_jobs:)
+      @event = event
+      @staged_jobs = staged_jobs.dup.freeze
+      freeze
+    end
+
+    def staged_subscribers
+      staged_jobs.map(&:class)
+    end
+
+    def subscriber_count
+      staged_jobs.length
+    end
+
+    def id
+      event.id
+    end
+
+    def inspect
+      "#<EventRail::StagedPublication event=#{event.inspect} staged=#{subscriber_count}>"
+    end
+  end
+end

data/lib/event_rail/version.rb

@@ -1,3 +1,3 @@
 module EventRail
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/event_rail.rb

@@ -30,8 +30,11 @@ require "event_rail/contract"
 require "event_rail/envelope"
 require "event_rail/internal/event_serializer"
 require "event_rail/internal/transaction"
+require "event_rail/internal/stager"
 require "event_rail/publication"
+require "event_rail/staged_publication"
 require "event_rail/publish"
+require "event_rail/stage"
 require "event_rail/railtie"
 
 # The subscription macro is class-level only: it changes nothing about serialization

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: event_rail
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Alex Dmitriev
@@ -140,6 +140,7 @@ files:
 - lib/event_rail/internal/notifications.rb
 - lib/event_rail/internal/portable_value.rb
 - lib/event_rail/internal/registry.rb
+- lib/event_rail/internal/stager.rb
 - lib/event_rail/internal/stamping.rb
 - lib/event_rail/internal/subscriber_execution.rb
 - lib/event_rail/internal/timestamp.rb
@@ -152,6 +153,8 @@ files:
 - lib/event_rail/publication.rb
 - lib/event_rail/publish.rb
 - lib/event_rail/railtie.rb
+- lib/event_rail/stage.rb
+- lib/event_rail/staged_publication.rb
 - lib/event_rail/subscriptions.rb
 - lib/event_rail/test_helper.rb
 - lib/event_rail/version.rb