julewire-ractor 1.1.2 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f80086f2967d5e948d9d0ce3cae9e1a55e5257bb1893a655d63aeac7f1909b30
-  data.tar.gz: 4eec5968bc6b73593b01d7531a8c7fc9550be48227eb23775a6c4b903184601e
+  metadata.gz: bdf4b664cc26510a153647b6041ba3d01804efda4b89eed4880194d9e81b82cd
+  data.tar.gz: 7660eff913795f731f31d508e2050320abf1842c967fdccb699c1c1620566a89
 SHA512:
-  metadata.gz: 9077d90838210803b36a82e4b7ab73dbba33af36f6313051242d8b8c9f2ac67d26b5dc3002139b66830699fda74f75a1e7eaa9cd68a46f84fca26b283681f990
-  data.tar.gz: 73a4ade8715104b2f740db61fb9aac3943c3f6ddfef1bfe64f46883e1b46a1a42272c789bff7254e4f5a3d5aa89889fdcb90267772c97c8ff95f2a85ebb18218
+  metadata.gz: b12284718b7f14a5c91cc735028ab5db62cb6e1c2ee4be8f399f17f56f99ad4e963ab22ce83199521bb5b4b8b157422d49e5d7247c5a30d64a90869e66617e17
+  data.tar.gz: c7d6266890e110b97110b9245ba06bcbc3dbe583360a2ce4cb130bc8e17c2a880152bb0929a9d73cb826d969d99d14aea3ccf3a6b282adb132d59d5c7f004cc5

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## Unreleased
 
+## 1.1.3 - 2026-08-09
+
+- Quiesce destination workers before process forks and reject forks with live
+  Ractors instead of rebuilding unsafe inherited VM state.
+- Serialize emit, close, and fork transitions; preserve terminal closure and
+  keep interrupted worker teardown retryable.
+- Require julewire-core 1.1.3.
+- Refresh development tooling and compatibility locksets.
+
 ## 1.1.2 - 2026-08-02
 
 - Refresh development and compatibility dependency locksets.

data/docs/bridge.md

@@ -79,6 +79,8 @@ remote request timeout is one second. `timeout: nil` remains unbounded.
 - `Julewire.labels`
 - `Julewire.health`
 - `Julewire.close`
+- `Julewire.before_fork!`
+- `Julewire.after_fork!`
 
 These belong to the parent runtime.
 
@@ -166,9 +168,26 @@ code needs Julewire facade calls to reach the parent runtime.
 
 ## Forking
 
-Do not fork a process with live Julewire ractor bridges. After a process fork,
-core calls the ractor integration after-fork hook and clears inherited bridge
-thread health. Create new ractors in the worker process after fork.
+CRuby cannot safely continue Ractor execution in a child forked while another
+Ractor is alive. Rebuilding inherited handles in the child is therefore too
+late.
+
+Stop application work, then call `Julewire.before_fork!` before the actual
+`Process.fork`. It flushes and stops Ractor destination workers without closing
+their outputs. It rejects the fork while a `Julewire.ractor` bridge or any other
+non-main Ractor remains active. Call `Julewire.after_fork!` in the child to start
+fresh destination workers, and in the parent too when it must resume logging
+between forks.
+
+```ruby
+before_fork { Julewire.before_fork! }
+on_worker_boot { Julewire.after_fork! }
+```
+
+The application must prevent concurrent emits and new Ractor creation between
+the pre-fork call and `Process.fork`; Julewire cannot make an external fork
+atomic. Calling `after_fork!` in an unprepared child raises
+`Julewire::UnsafeForkError` without touching inherited Ractor handles.
 
 ## Runtime Promise
 

data/julewire-ractor.gemspec

@@ -32,6 +32,6 @@ Gem::Specification.new do |spec|
   spec.executables = []
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "julewire-core", ">= 1.1.0"
+  spec.add_dependency "julewire-core", ">= 1.1.3"
   spec.add_dependency "zeitwerk", ">= 2.8.1"
 end

data/lib/julewire/ractor/bridge.rb

@@ -48,6 +48,18 @@ module Julewire
 
         def after_fork! = Stats.after_fork!
 
+        def before_fork!
+          active_bridges = health.fetch(:active_threads)
+          if active_bridges.positive?
+            raise UnsafeForkError,
+                  "cannot fork while #{active_bridges} Julewire ractor bridge thread(s) are active"
+          end
+
+          return if ::Ractor.count.eql?(1)
+
+          raise UnsafeForkError, "cannot fork while non-main Ractors are active"
+        end
+
         private
 
         def start_bridge(port:, runtime:, ractor: nil)

data/lib/julewire/ractor/destination.rb

@@ -49,8 +49,8 @@ module Julewire
       ].freeze
       DEFAULT_MAX_QUEUE = 1024
       DEFAULT_REQUEST_TIMEOUT = 1
-      WORKER_STOP_MESSAGE = { command: :close_worker }.freeze
-      private_constant :COUNTER_KEYS, :QueueSlots, :WORKER_STOP_MESSAGE
+      WORKER_QUIESCE_MESSAGE = { command: :quiesce_worker }.freeze
+      private_constant :COUNTER_KEYS, :QueueSlots, :WORKER_QUIESCE_MESSAGE
 
       attr_reader :name
 
@@ -84,25 +84,23 @@ module Julewire
         @request_timeout = request_timeout
         @on_drop = on_drop
         @on_failure = on_failure
-        initialize_tracking
+        @fork_lifecycle_mutex = Mutex.new
+        initialize_tracking(closed: false)
         start_worker
       end
 
       def emit(record)
         increment(:received)
-        return drop(:closed_dropped, record) if closed?
-        return drop(:queue_full_dropped, record) unless @queue_slots.reserve
-
-        begin
-          degradation_marker = @health.degradation_marker
-          @port.send({ command: :emit, degradation_marker: degradation_marker, record: record })
-          increment(:queued)
-        rescue StandardError => e
-          release_slot
-          record_failure(e, phase: :ractor_send)
+        outcome = enqueue(record)
+        case outcome
+        when :closed
+          drop(:closed_dropped, record)
+        when :queue_full
+          drop(:queue_full_dropped, record)
+        when StandardError
+          record_failure(outcome, phase: :ractor_send)
           drop(:send_error, record)
         end
-        nil
       end
 
       def flush(timeout: nil)
@@ -111,20 +109,61 @@ module Julewire
 
       def close(timeout: nil)
         timeout = lifecycle_timeout(timeout)
-        @closed.set(true)
-        result = request(:close, timeout: timeout, allow_closed: true)
-        close_ports(timeout: timeout)
-        result
+        @fork_lifecycle_mutex.synchronize do
+          @closed.set(true)
+          prepared_for_fork = @prepared_for_fork
+          @prepared_for_fork = false
+          unless @worker
+            @owned_output_close_pending ||= prepared_for_fork && @close_output
+            return true unless @owned_output_close_pending
+
+            begin
+              start_worker
+            rescue StandardError => e
+              record_failure(e, phase: :worker_start)
+              return false
+            end
+          end
+
+          result = request(:close, timeout: timeout, allow_closed: true)
+          begin
+            close_ports(timeout: timeout)
+            @owned_output_close_pending = false if result
+            result
+          rescue Core::Error => e
+            record_failure(e, phase: :worker_stop)
+            false
+          end
+        end
       end
 
-      def after_fork!
-        if (@process_id - Process.pid).zero? && !close_ports(timeout: @request_timeout)
-          raise Core::Error, "ractor destination worker did not stop within #{@request_timeout} seconds"
+      def before_fork!(timeout: nil)
+        timeout = lifecycle_timeout(timeout)
+        @fork_lifecycle_mutex.synchronize do
+          validate_before_fork_process!
+          deadline = Core::Scheduling::Deadline.for(timeout)
+          remaining_timeout = -> { Core::Scheduling::Deadline.remaining(deadline) }
+          if closed?
+            close_ports(timeout: remaining_timeout.call) if @worker
+            return self
+          end
+
+          @closed.set(true)
+          flush_before_fork!(remaining_timeout.call)
+          stop_before_fork!(remaining_timeout.call)
         end
+        self
+      rescue StandardError => e
+        record_failure(e, phase: :before_fork)
+        raise
+      end
 
-        initialize_tracking
-        start_worker
+      def after_fork!
+        @fork_lifecycle_mutex.synchronize { resume_after_fork! }
         self
+      rescue UnsafeForkError => e
+        record_failure(e, phase: :after_fork)
+        raise
       rescue StandardError => e
         record_failure(e, phase: :after_fork)
         self
@@ -153,15 +192,75 @@ module Julewire
 
       private
 
+      def enqueue(record)
+        @fork_lifecycle_mutex.synchronize do
+          return :closed if closed?
+          return :queue_full unless @queue_slots.reserve
+
+          begin
+            @port.send(
+              { command: :emit, degradation_marker: @health.degradation_marker, record: record }
+            )
+            increment(:queued)
+          rescue StandardError => e
+            release_slot
+            e
+          end
+        end
+      end
+
+      def validate_before_fork_process!
+        return if @process_id == Process.pid
+        return unless @worker
+
+        raise UnsafeForkError,
+              "ractor destination was inherited without Julewire.before_fork! in the parent process"
+      end
+
+      def validate_after_fork_process!
+        return if @process_id == Process.pid
+        return unless @worker
+
+        raise UnsafeForkError,
+              "ractor destination was inherited without Julewire.before_fork! in the parent process"
+      end
+
+      def flush_before_fork!(timeout)
+        return if request(:flush, timeout: timeout, allow_closed: true)
+
+        @closed.set(false)
+        raise Core::Error, "ractor destination could not flush before fork"
+      end
+
+      def stop_before_fork!(timeout)
+        # Mark preparation before teardown so every failure remains recoverable
+        # through the paired after-fork rollback.
+        @prepared_for_fork = true
+        @port.send(WORKER_QUIESCE_MESSAGE)
+        close_ports(timeout: timeout)
+      end
+
+      def resume_after_fork!
+        validate_after_fork_process!
+        return unless @prepared_for_fork
+
+        # Quiesce is terminal and ordered after the completed flush. Replace
+        # any retained handles before starting the recovery worker.
+        initialize_tracking(closed: true)
+        start_worker
+        @closed.set(false)
+        @prepared_for_fork = false
+      end
+
       def validate_callable(callable, name:)
         Core::Validation.validate_callable!(callable, name: name)
         callable
       end
 
-      def initialize_tracking
+      def initialize_tracking(closed:)
         @process_id = Process.pid
         @scheduler = ReplyTimeoutScheduler.new(timeout_value: false)
-        @closed = Concurrent::AtomicReference.new
+        @closed = Concurrent::AtomicReference.new(closed)
         @health = Core::Integration::DestinationHealth.new(counter_keys: COUNTER_KEYS, failure_counter: nil)
         @queue_slots = QueueSlots.new(max_queue: @max_queue)
         @worker_health = Concurrent::AtomicReference.new
@@ -270,30 +369,20 @@ module Julewire
       def closed? = @closed.get
 
       def close_ports(timeout:)
-        worker_stopped = true
         begin
-          if @worker
-            begin
-              @port.send(WORKER_STOP_MESSAGE)
-            rescue ::Ractor::ClosedError
-              # A stopped worker no longer accepts commands. Still collect it
-              # below so an abnormal exit remains observable.
-            end
-            worker_stopped = wait_for_worker(timeout)
-          end
+          worker_stopped = wait_for_worker(timeout)
         rescue ::Ractor::RemoteError => e
           record_failure(e, phase: :worker_stop)
           worker_stopped = true
         ensure
-          @ack_thread&.kill
-          @ack_thread&.join
           PortLifecycle.close(@ack_port)
+          @ack_thread&.kill&.join
           @port = @worker = nil if worker_stopped
           @ack_port = nil
           @ack_thread = nil
         end
 
-        worker_stopped
+        raise Core::Error, "ractor destination worker did not stop within #{timeout} seconds" unless worker_stopped
       end
 
       def wait_for_worker(timeout)

data/lib/julewire/ractor/destination_worker.rb

@@ -44,15 +44,21 @@ module Julewire
 
       def run(command_port:, ack_port:)
         @ack_port = ack_port
+        close_owned_output = true
         loop do
           message = command_port.receive
           current_command = command(message)
           break if current_command == :close_worker
 
+          if current_command == :quiesce_worker
+            close_owned_output = false
+            break
+          end
+
           break if dispatch(message, current_command) == :close
         end
       ensure
-        close_output
+        close_output if close_owned_output
       end
 
       private

data/lib/julewire/ractor/fanout.rb

@@ -34,15 +34,28 @@ module Julewire
 
       def after_fork!
         @health.recover_if_successful do
-          @destinations.each do |destination|
-            destination.after_fork! if destination.respond_to?(:after_fork!)
-          rescue StandardError => e
-            record_failure(e, action: :after_fork, destination: destination.name)
-          end
+          @destinations.each { call_destination_after_fork(it) }
         end
         self
       end
 
+      def before_fork!(timeout: nil)
+        prepared = []
+        Core::Validation.validate_timeout!(timeout, name: :timeout)
+        deadline = Core::Scheduling::Deadline.for(timeout)
+        @destinations.each do |destination|
+          next unless destination.respond_to?(:before_fork!)
+
+          prepared << destination
+          result = destination.before_fork!(timeout: Core::Scheduling::Deadline.remaining(deadline))
+          raise Core::Error, "destination #{destination.name} rejected before_fork" if result == false
+        end
+        self
+      rescue StandardError
+        prepared.reverse_each { call_destination_after_fork(it) }
+        raise
+      end
+
       def resource_identity = self
 
       def health
@@ -55,6 +68,14 @@ module Julewire
 
       private
 
+      def call_destination_after_fork(destination)
+        destination.after_fork! if destination.respond_to?(:after_fork!)
+      rescue Core::UnsafeForkError
+        raise
+      rescue StandardError => e
+        record_failure(e, action: :after_fork, destination: destination.name)
+      end
+
       def normalize_destination(value)
         destination = value.is_a?(Hash) ? Destination.new(**value) : value
         Core::Destinations::Registry.validate!(destination)

data/lib/julewire/ractor/remote_runtime.rb

@@ -76,6 +76,10 @@ module Julewire
         raise Core::Error, "Julewire.after_fork! is not available inside Julewire.ractor"
       end
 
+      def before_fork!(**)
+        raise Core::Error, "Julewire.before_fork! is not available inside Julewire.ractor"
+      end
+
       def health
         raise Core::Error, "Julewire.health is not available inside Julewire.ractor"
       end

data/lib/julewire/ractor/version.rb

@@ -2,6 +2,6 @@
 
 module Julewire
   module Ractor
-    VERSION = "1.1.2"
+    VERSION = "1.1.3"
   end
 end

data/lib/julewire/ractor.rb

@@ -38,6 +38,7 @@ module Julewire
   loader = Zeitwerk::Loader.for_gem_extension(self)
   loader.setup
   Core::Destinations.register(:ractor) { |name:, **options| Ractor::Destination.new(name: name, **options) }
+  Core::Integration::Lifecycle.register_before_fork(:ractor, component: :bridge) { Ractor::Bridge.before_fork! }
   Core::Integration::Lifecycle.register_after_fork(:ractor, component: :bridge) { Ractor::Bridge.after_fork! }
 
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: julewire-ractor
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.3
 platform: ruby
 authors:
 - Alexander Grebennik
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 1.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 1.1.3
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement